> ## 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.

# Providers: Connect GitHub, CircleCI, and Linear to AgentRail

> Use agentrail provider connect to wire up GitHub for PRs and review, CircleCI for CI status, and Linear for issue import with readiness verification.

Providers are the external services AgentRail connects to in order to receive issues, submit pull requests, track CI, and observe code review. In local OSS mode, you supply your own credentials and AgentRail calls provider APIs from your machine. Provider connections are optional — you can run AgentRail without any providers for local evaluation — but you need at least one configured to handle real issue intake and PR submission.

## Connecting a provider

Use the interactive setup command for any provider:

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

Each `provider connect` command:

1. Prompts for credentials in a hidden input (your secrets are not echoed to the terminal).
2. Writes the credentials to a local env file under `~/.agentrail`.
3. Runs a full provider readiness check — the same check used by `agentrail provider doctor`.
4. Applies safe local fixes where it can.
5. Reports exact next steps for any remaining blockers that require changes in the provider account or repo settings (things AgentRail cannot change for you).

<Tip>
  For non-interactive automation or CI pipelines, set `GITHUB_TOKEN`, `CIRCLECI_TOKEN`, or `LINEAR_API_KEY` as environment variables before starting the server. The `provider connect` interactive flow is the recommended path for local setup.
</Tip>

## GitHub

GitHub is the primary provider for PR submission, CI observation (GitHub Actions), and code review feedback.

**What GitHub enables:**

* `adapter_managed` PR submission — AgentRail creates or reuses pull requests from the task's persisted source metadata and returns `prUrl` and `prNumber`.
* GitHub Actions CI status — AgentRail surfaces a compact CI summary at `/tasks/{id}/ci-status`.
* Code review feedback — AgentRail observes review decisions and requested changes at `/tasks/{id}/review-feedback`.

**Review policy.** During `provider connect github` (and during `agentrail init`), you choose how AgentRail handles code review before shipping:

| Policy           | Behavior                                                                                                    |
| ---------------- | ----------------------------------------------------------------------------------------------------------- |
| `github_rules`   | Follow GitHub's own branch protection and review signals. This is the default.                              |
| `always_require` | Always require an approval for AgentRail-created PRs before shipping, even if the repo does not require it. |
| `never_require`  | Skip approval waits once CI is green.                                                                       |

<Warning>
  Explicit review change requests still block ship regardless of your review policy setting. The `never_require` policy only skips the approval wait when there are no outstanding change requests.
</Warning>

## CircleCI

CircleCI provides CI status for tasks that use CircleCI pipelines instead of GitHub Actions.

**What CircleCI enables:**

* CI status observation for tasks using CircleCI pipelines.
* Pipeline-run API access when automatic branch builds are not available.
* Inbound webhook verification using `CIRCLECI_WEBHOOK_SECRET` — configure your CircleCI webhook to point to your AgentRail server's `/providers/circleci/webhooks` path.

**During `provider connect circleci`:**

* AgentRail prompts for your full CircleCI project slug in the format `circleci/<org-id>/<project-id>`.
* It verifies project access.
* If `.circleci/config.yml` is missing and AgentRail can infer a safe starter Node.js workflow, the connect command creates it.
* If automatic CircleCI branch builds are not available, AgentRail configures the pipeline-run API when your token can access a pipeline definition.
* If any settings cannot be fixed locally, setup reports the exact blocker and what you need to change in your CircleCI account.

## Linear

Linear provides issue intake. After connecting, you can import individual issues into AgentRail's task queue.

**Import an issue:**

```bash theme={null}
agentrail linear import ENG-123
```

You can also import by issue URL or issue UUID. Imported issues go through the routing engine — if routing is not configured, the import fails closed rather than creating an unassigned task.

## Checking provider health

Two commands give you visibility into provider status at any time:

```bash theme={null}
# Summary of all configured providers
agentrail provider status

# Detailed readiness check for all or a specific provider
agentrail provider doctor
agentrail provider doctor github
agentrail provider doctor circleci
agentrail provider doctor linear
```

For a full readiness check (not just a token probe), use:

```bash theme={null}
agentrail provider test github
agentrail provider test circleci
agentrail provider test linear
```

<Note>
  `agentrail provider test <provider>` runs the same readiness engine as `agentrail provider doctor <provider>`. A passing test means the provider is ready for the full AgentRail lifecycle — not merely that a token exists and the API is reachable.
</Note>

## List all configured providers

```bash theme={null}
agentrail provider list
```

## OSS vs. planned Cloud

In local OSS mode, you own the provider integration operations: credential storage, webhook exposure, TLS, HMAC validation, missed-event recovery, rate-limit handling, secret rotation, and upgrades.

Planned AgentRail Cloud will manage these operations on your behalf — OAuth flows, credential rotation, webhook endpoints, signature validation, dedupe, retries, and replay/backfill. Cloud is not currently generally available.