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

# Connect your GitHub account and repos to AgentRail

> Link GitHub to AgentRail for PR submission, GitHub Actions CI status, and review observation. Covers review policy options and health check commands.

Connecting GitHub to AgentRail enables three things: AgentRail can create and reuse pull requests through its provider adapter, read GitHub Actions CI status for agent branches, and observe code review feedback so it knows when to relaunch an agent for fixes. Run `agentrail provider connect github` to set this up interactively.

## Connect GitHub

```bash theme={null}
agentrail provider connect github
```

The interactive setup asks for your GitHub token in a hidden prompt, validates credentials, runs provider readiness checks, applies safe local fixes where it can, and prints exact next steps for anything only your GitHub account or repo owner can change.

<Note>
  For non-interactive environments such as CI pipelines, set the `GITHUB_TOKEN` environment variable before running the connect command.

  ```bash theme={null}
  export GITHUB_TOKEN=ghp_...
  agentrail provider connect github
  ```
</Note>

## What it sets up

Once connected, AgentRail uses GitHub for:

| Capability               | Description                                                                                                                                            |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| PR submission            | AgentRail creates or reuses a pull request from persisted task source metadata. The response includes the PR URL and whether it was created or reused. |
| GitHub Actions CI status | AgentRail reads check run results for agent branches and surfaces compact pass/fail summaries.                                                         |
| Code review observation  | AgentRail watches review decisions and blocks ship until review requirements are satisfied.                                                            |

## Review policy

During `agentrail provider connect github`, you choose a review policy that controls whether AgentRail waits for PR approval before shipping.

| Policy                   | Behavior                                                                                                             |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| `github-rules` (default) | AgentRail follows GitHub's own review signals for the repository.                                                    |
| `always-require`         | AgentRail always requires at least one approval for AgentRail-created PRs, regardless of branch protection settings. |
| `never-require`          | AgentRail skips approval waits once CI is green.                                                                     |

<Warning>
  Explicit "Request changes" review decisions always block ship, regardless of which policy you choose. The agent must address the review comments and report completion before AgentRail will attempt to ship again.
</Warning>

## Health checks

Use these commands to verify that your GitHub connection is working correctly.

<CodeGroup>
  ```bash Doctor theme={null}
  agentrail provider doctor github
  ```

  ```bash Test theme={null}
  agentrail provider test github
  ```
</CodeGroup>

`provider test` runs the same readiness check as `provider doctor` — it is not a lightweight token probe. A passing test means GitHub is ready for AgentRail's full lifecycle, not merely that the token exists.

You can also check the status of all connected providers at once:

```bash theme={null}
agentrail provider status
agentrail provider doctor
```

## Troubleshooting

| Symptom                              | Likely cause                                                                    | Fix                                                                                                      |
| ------------------------------------ | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| CI stays pending                     | No live GitHub adapter configured, or task is missing persisted source metadata | Confirm `GITHUB_TOKEN` is set, then inspect or repair `task.source` with `agentrail task source repair`. |
| PR submission returns `404`          | No live adapter matches the task                                                | Verify the task has the required `source` metadata and that `GITHUB_TOKEN` is present.                   |
| Review observation not blocking ship | Review policy is `never-require`                                                | Change the policy to `github-rules` or `always-require` via `agentrail provider connect github`.         |