Skip to main content

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.

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

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: 
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.
For non-interactive environments, set environment variables before running the connect command.
export CIRCLECI_TOKEN=...
export CIRCLECI_WEBHOOK_SECRET=...
agentrail provider connect circleci

​
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

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

​
Health check

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: 
agentrail provider status
agentrail provider doctor

​
Troubleshooting

SymptomLikely causeFix
CI stays pendingCIRCLECI_TOKEN not set, or task is missing ciProvider: "circleci" in source metadataConfirm the token is set and inspect task.source.
Webhook requests rejectedCIRCLECI_WEBHOOK_SECRET missing or mismatchedSet the env var to the same secret configured in your CircleCI webhook settings.
Pipeline not triggeredToken lacks pipeline access and no config fallback foundCheck that the token has access to a pipeline definition in the CircleCI project settings.
Setup reports a blocker it cannot fixCircleCI project or repo settings require account-level changesFollow the exact steps provider connect circleci prints for each unresolved blocker.