> ## 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 CircleCI pipelines and projects to AgentRail

> Link CircleCI to AgentRail to track pipeline status for agent branches. Covers project slug, config file creation, webhook verification, and health checks.

Connecting CircleCI to AgentRail lets your agents get compact CI status summaries instead of parsing raw pipeline logs. AgentRail verifies your project access, creates a starter `.circleci/config.yml` if one is missing and it is safe to do so, and configures how it will fetch pipeline results for agent branches. Run `agentrail provider connect circleci` to get started.

## Connect CircleCI

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

The interactive setup prompts for your CircleCI API token in a hidden prompt, then asks for the full CircleCI project slug in this format:

```text theme={null}
circleci/<org-id>/<project-id>
```

After you provide the slug, AgentRail:

1. Verifies your token has access to the project.
2. Checks the repo for a `.circleci/config.yml` file.
3. Creates a starter Node workflow config if the file is missing and a safe inference is possible.
4. Configures the CircleCI pipeline-run API as a fallback if automatic branch builds are not available and your token can access a pipeline definition.
5. Runs provider readiness checks and reports any blockers it cannot fix locally.

<Note>
  For non-interactive environments, set environment variables before running the connect command.

  ```bash theme={null}
  export CIRCLECI_TOKEN=...
  export CIRCLECI_WEBHOOK_SECRET=...
  agentrail provider connect circleci
  ```
</Note>

## Webhook verification

AgentRail verifies inbound CircleCI webhook requests using the `CIRCLECI_WEBHOOK_SECRET` environment variable. To receive push-based pipeline status updates instead of polling, configure your CircleCI webhook to deliver to your AgentRail server's `/providers/circleci/webhooks` path and set `CIRCLECI_WEBHOOK_SECRET` in your server environment before starting AgentRail.

## What it sets up

| Capability                | Description                                                                                                                 |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| CI status                 | AgentRail reads CircleCI pipeline results for agent branches and surfaces compact pass/fail summaries to your agents.       |
| Pipeline-run API fallback | If automatic branch builds are not available, AgentRail uses the pipeline-run API to trigger and track builds.              |
| Webhook delivery          | Inbound CircleCI webhooks update task CI state in real time when `CIRCLECI_WEBHOOK_SECRET` is configured.                   |
| Config file creation      | AgentRail creates `.circleci/config.yml` with a starter workflow when the file is missing and a safe inference is possible. |

## Health check

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

`provider doctor` runs full provider readiness — it is not just a token check. A passing result means CircleCI is ready for AgentRail's lifecycle operations.

You can also check all providers at once:

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

## Troubleshooting

| Symptom                               | Likely cause                                                                             | Fix                                                                                        |
| ------------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| CI stays pending                      | `CIRCLECI_TOKEN` not set, or task is missing `ciProvider: "circleci"` in source metadata | Confirm the token is set and inspect `task.source`.                                        |
| Webhook requests rejected             | `CIRCLECI_WEBHOOK_SECRET` missing or mismatched                                          | Set the env var to the same secret configured in your CircleCI webhook settings.           |
| Pipeline not triggered                | Token lacks pipeline access and no config fallback found                                 | Check that the token has access to a pipeline definition in the CircleCI project settings. |
| Setup reports a blocker it cannot fix | CircleCI project or repo settings require account-level changes                          | Follow the exact steps `provider connect circleci` prints for each unresolved blocker.     |