> ## Documentation Index
> Fetch the complete documentation index at: https://autodock.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub App

> Turn every PR into a command center for preview environments

# GitHub App

Autodock turns your GitHub PR page into a command center for a preview environment. From spinning up
environments to automated testing to leaving artifacts, the GitHub App makes sure your PR is on-spec
and bug-free while giving you full SSH access to the dev boxes that back these environments.

<Tip>
  **No configuration required.** Install the app, and Autodock posts a comment on every PR with
  options to spin up a preview. Claude analyzes your changes and handles the rest.
</Tip>

## Quick Start

1. **Install the GitHub App** at
   [github.com/apps/autodock-preview](https://github.com/apps/autodock-preview)
2. **Link your account** - You'll be redirected to Autodock to connect the installation
3. **Open a PR** - Autodock automatically posts a comment with preview options

That's it. No YAML files, no secrets, no workflow configuration.

## How It Works

When you open a pull request:

1. Autodock analyzes your PR to determine if a preview environment would be helpful
2. If recommended, you click to spin up a preview environment
3. Claude Code clones your repo, installs dependencies, builds, and runs setup
4. The PR comment updates in real-time with progress and connection details
5. Push more commits and changes sync automatically
6. Close the PR and the environment is destroyed

## PR Comment States

The Autodock PR comment acts as a live dashboard for your preview environment. Here are all the
possible states you'll encounter:

### Setup Required

**When:** The GitHub App is installed but hasn't been linked to an Autodock account yet.

**What you see:** A message prompting you to complete setup by linking the installation to your
Autodock account. Once linked, preview environments will be created automatically for future PRs.

**Action:** Click the setup link and sign in or create an Autodock account.

***

### Analyzing

**When:** A PR is opened and Autodock is analyzing the changes.

**What you see:** Claude is reviewing the PR to determine if a preview environment would be helpful.
This typically takes a few seconds.

**Action:** Wait for analysis to complete.

***

### Not Recommended

**When:** Claude analyzed the PR and determined a preview isn't needed.

**What you see:** An explanation of why a preview isn't recommended (e.g., documentation-only
changes, config tweaks). A button to spin up a preview anyway if you want one.

**Action:** Click "Spin up environment" if you still want a preview.

***

### Trigger Posted

**When:** Claude recommends a preview and is waiting for you to trigger it.

**What you see:** A button to spin up the preview environment. Options for different setup modes.

**Action:** Click the button to start provisioning.

***

### Claiming Environment

**When:** Autodock is claiming a VM from the warm pool.

**What you see:** Progress indicators showing the setup stage. Once claimed, MCP and SSH connection
commands appear (you can connect immediately even while setup continues).

**Action:** Optionally connect early via MCP or SSH to watch setup in real-time.

***

### Cloning Repository

**When:** The environment is cloning your PR branch.

**What you see:** Progress indicator updated to show cloning is in progress. Connection info
available.

**Action:** Wait for cloning to complete, or connect to watch.

***

### Installing Dependencies

**When:** Claude is installing dependencies (npm install, pip install, etc.).

**What you see:** Progress indicator showing installation step. Connection info available.

**Action:** Wait for installation to complete.

***

### Building Project

**When:** Claude is building your project (next build, webpack, etc.).

**What you see:** Progress indicator showing build step. Connection info available.

**Action:** Wait for build to complete.

***

### Running Setup

**When:** Claude is running final setup (starting dev servers, exposing ports, etc.).

**What you see:** Progress indicator showing setup step. Connection info available.

**Action:** Wait for setup to complete.

***

### Ready

**When:** Your preview environment is fully operational.

**What you see:**

* Preview URL (if a web server is exposed)
* MCP connection command
* SSH access details
* Setup summary from Claude
* Instructions for running tests via `/autodock-test` comments

**Action:** Click the preview URL, connect via MCP, or run tests.

***

### Waiting for Secrets

**When:** Your project requires environment variables that weren't provided.

**What you see:**

* List of missing environment variables
* A curl command to upload your local `.env` files securely
* Instructions for running the upload command

**Action:** Run the provided curl command in your project directory. Setup continues automatically
after upload.

***

### Syncing

**When:** You pushed new commits and changes are syncing to the environment.

**What you see:** Progress indicator showing sync is in progress. Environment remains accessible.

**Action:** Wait for sync to complete. You can keep using the environment.

***

### Running Automated Tests

**When:** Automated tests are running against your preview.

**What you see:** A table with test checks (page load, console errors, network, auth test) showing
pending status.

**Action:** Wait for tests to complete.

***

### Automated Tests Complete

**When:** Automated tests have finished.

**What you see:**

* Test results table with pass/fail status
* Page load time
* Console error count
* Network failure count
* Auth test result
* Screenshots (if captured)
* Button to re-run tests

**Action:** Review results. Click re-run if needed.

***

### Running User Test

**When:** You triggered a test via `/autodock-test <prompt>` comment.

**What you see:**

* The test prompt you provided
* Live progress of test steps
* Status for each step (pending, running, passed, failed)

**Action:** Wait for the test to complete.

***

### User Test Complete

**When:** A user-triggered test has finished.

**What you see:**

* Test results with step-by-step breakdown
* Screenshots captured during the test
* Summary of what happened
* Previous test results (up to 3 runs)
* Button to re-run the last test

**Action:** Review results. Run additional tests as needed.

***

### Failed

**When:** Setup encountered an error and couldn't complete.

**What you see:**

* Error message explaining what went wrong
* Exit code (if applicable)
* Link to full session log

**Action:** Review the error and session log. Fix the issue and push a new commit, or use MCP/SSH to
debug manually.

***

### Destroyed

**When:** The environment has been destroyed (typically when PR is closed).

**What you see:** Confirmation that the environment is destroyed.

**Action:** No action needed. Open a new PR to get a new preview.

## Running Tests

Once your environment is ready, you can run tests by commenting on the PR:

```
/autodock-test Navigate to the homepage and verify it loads correctly
```

Claude will:

1. Open a browser in the environment
2. Execute the test steps you described
3. Capture screenshots at each step
4. Report results back in the PR comment

### Example Test Prompts

* `/autodock-test Test the login flow with valid credentials`
* `/autodock-test Click the sign up button and fill out the registration form`
* `/autodock-test Navigate to /dashboard and verify user data displays`
* `/autodock-test Add an item to the cart and proceed to checkout`

## Troubleshooting

**Environment is stuck provisioning**

Check the session log link in the PR comment. You can also connect via MCP or SSH to see what's
happening in real-time.

**Secrets aren't being recognized**

Make sure your `.env` files are in the project directory when you run the upload command. The script
searches for all `.env*` files.

**Preview URL returns 502**

Your dev server might not be running or might be bound to localhost. Autodock exposes ports bound to
`0.0.0.0`. Check if the server is running via SSH.

**GitHub App not posting comments**

Verify the app is installed for your repository and linked to an Autodock account. Check the
installation settings at
[github.com/settings/installations](https://github.com/settings/installations).