# CircleCI - Full Documentation > This is the expanded llms.txt for CircleCI, containing full content from the > product pages for AI/LLM consumption with larger context windows. > > CircleCI is a continuous integration and delivery (CI/CD) platform that > validates every change, whether it was written by a person, an agent, or a > model. It runs pipelines on Docker, Linux, macOS, Windows, GPU, Arm and > self-hosted compute, and integrates with GitHub, GitLab and Bitbucket. > > The concise index is at https://circleci.com/llms.txt. The documentation index > is at https://circleci.com/docs/llms.txt, and every documentation page is > available as markdown by appending `index.md` to its URL. --- ## Platform Overview --- title: "CircleCI - Validate every change, autonomously" description: "The compute, automation, and insights that power modern software delivery, from flexible execution to autonomous AI-driven validation." url: "https://circleci.com/product/" --- # CircleCI > Validate every change, autonomously. Ship confidently at AI speed with a > validation engine built for how code is generated today. CircleCI runs the tests, checks and deployments that decide whether a change is safe to ship. A single `config.yml` file describes the whole pipeline, and CircleCI provisions the compute, runs the work in parallel, caches what it can reuse, and reports back to the pull request. ## Key Features - Test and validate change from any source: your team, your agents, and the models you depend on. - Fast feedback, so slow validation does not bottleneck the flow of changes. - Flexible execution across Docker, Linux, macOS, Windows, GPU, Arm and self-hosted machines. - Build optimization: parallelism, dependency and Docker layer caching, test splitting, and smart reruns of only the failed tests. - Metrics and insights on duration, queueing, success rate, flaky tests and credit spend. - Release orchestration with deployment visibility, progressive rollout and rollback. - Security controls: secrets management, granular access control, policy-as-code and audit trails. - Reusable configuration through orbs, and a registry of pre-built integrations. ## Use Cases - Continuous integration: run the test suite on every commit and pull request, across languages and platforms. - Continuous delivery: deploy on merge, with approvals, environments and rollback. - Mobile delivery: build and sign iOS and Android apps on managed macOS and Linux machines. - Machine learning and AI workloads: run training and evaluation jobs on GPU resource classes. - Agentic development: give coding agents validation and guardrails at the speed they generate changes. ## Resources - Product overview: https://circleci.com/product/ - Feature list: https://circleci.com/product/features/ - Documentation: https://circleci.com/docs/ - Product demo: https://circleci.com/product/demo/ - Pricing: https://circleci.com/pricing/ - Sign up: https://circleci.com/signup/ Source: https://circleci.com/product/ --- ## Chunk --- title: "Chunk by CircleCI - Validation that keeps up with your agents" description: "A sidecar that runs validation in the cloud while your AI agent keeps working, returning results far faster than a full CI run." url: "https://chunk.ai" --- # Chunk > Validation that keeps up with your agents. Catch failures before the push. > Ship cleaner. Move faster. Chunk is CircleCI's tool for agentic development. It syncs local code to a Linux microVM and runs tests there while the agent continues working, so validation happens inside the agent loop rather than after the push. It auto-detects the stack and triggers validation hooks when an agent pauses, returning deterministic feedback the agent can act on. ## Key Features - Runs lightweight validation checks in a cloud microVM while the agent keeps working. - Auto-detects the tech stack and fires validation hooks at agent pause points. - Deterministic feedback through hooks, so agents stay aligned with what the repository actually requires. - Sidecar validation without spending the agent's context on running tests locally. - Chunk Tasks monitors, troubleshoots and optimizes CI pipelines autonomously. - Works with Claude Code, Cursor and other coding agents. - Free on every CircleCI plan. ## Use Cases - Catching a failing test before an agent opens a pull request. - Keeping a fleet of agents productive without filling the review queue with broken changes. - Fixing flaky tests, repairing builds and optimizing pipelines without a human driving each step. ## Resources - Chunk: https://chunk.ai - AI agents on CircleCI: https://circleci.com/solutions/ai-agents/ Source: https://chunk.ai --- ## MCP Server --- title: "CircleCI MCP Server" description: "Connect an AI assistant to your CircleCI data to debug failures, analyze test results and improve pipelines in natural language." url: "https://circleci.com/product/mcp/" --- # MCP Server > Connect your AI assistant to your CircleCI data to debug failures, analyze > test results, and improve pipelines using natural language. The CircleCI MCP server exposes build logs, pipeline status, configuration changes and workflow metrics to AI assistants through the Model Context Protocol, so a developer can diagnose a failure without leaving the editor. ## Key Features - Diagnose failing builds from structured error summaries rather than raw logs. - Connect a regression to the commits and configuration changes that preceded it. - Identify flaky test patterns from historical runs. - Suggest pipeline and configuration improvements. - Bring CI/CD context into the editor, alongside the code being changed. ## Setup - Hosted server at `https://mcp.circleci.com/v1/mcp`, authenticated with OAuth 2.0 or a personal API token. - Local server built into the CircleCI CLI, authenticated with `circleci auth login` or the `CIRCLE_TOKEN` environment variable. Supported clients include Claude Code, Claude Desktop, claude.ai, Cursor, VS Code and Windsurf, each with one-command configuration. ## Resources - MCP server: https://circleci.com/product/mcp/ - Setup guide: https://circleci.com/docs/guides/toolkit/mcp-server/ - OAuth 2.0 access: https://circleci.com/docs/guides/toolkit/oauth-dynamic-client-registration/ Source: https://circleci.com/product/mcp/ --- ## AI Agents --- title: "Scale safely with AI agents - CircleCI" description: "Real-time feedback and policy guardrails for AI agents, so you can ship code as fast as your fleet can generate it." url: "https://circleci.com/solutions/ai-agents/" --- # AI Agents > Boost productivity without losing control. Give your agents real-time feedback > and policy guardrails so you can ship code as fast as your fleet can generate > it. Agents generate changes faster than review queues drain. CircleCI's answer is autonomous validation: agents get feedback inside their own loop, and policy guardrails decide what is allowed to proceed. ## Key Features - Autonomous validation at AI speed, so agents resolve their own failures. - Policy guardrails and approval rules that hold regardless of who or what wrote the change. - Every commit, log and test result streamed through MCP, so agents act on fresh data. - Full inspection of what an agent changed, and why a pipeline accepted or rejected it. - Chunk sidecars for validation that does not consume the agent's context window. ## Use Cases - Running a fleet of coding agents against a shared repository without losing control of what merges. - Giving an agent the CI evidence it needs to fix its own failing test. - Enforcing organization-wide rules on agent-authored changes through config policies. ## Resources - AI agents: https://circleci.com/solutions/ai-agents/ - AI development: https://circleci.com/solutions/ai/ - Chunk: https://chunk.ai - MCP server: https://circleci.com/product/mcp/ Source: https://circleci.com/solutions/ai-agents/ --- ## Execution Environments --- title: "Execution environments - CircleCI" description: "Run CI/CD jobs on Docker, Linux, Android, macOS, Windows, GPU, Arm, or your own infrastructure." url: "https://circleci.com/execution-environments/" --- # Execution Environments > Enjoy the flexibility to use any execution environment. Each job in a CircleCI configuration names an executor and a resource class, which decide the machine it runs on and how much CPU and memory it gets. ## Available Environments - **Docker** - native support for building inside Docker containers on x86 and Arm, using CircleCI convenience images or images pulled from a public or private registry. https://circleci.com/execution-environments/docker/ - **Linux VM** - a Linux virtual machine with full control over OS resources, including emulator support. https://circleci.com/execution-environments/linux/ - **Android** - clean Linux VMs with the Android SDK preinstalled, and matrix jobs for testing across OS versions. https://circleci.com/execution-environments/linux/android/ - **macOS** - fully managed macOS virtual machines for building and testing iOS, watchOS and tvOS apps. https://circleci.com/execution-environments/macos/ - **Windows** - build and test Windows applications with PowerShell, Bash or cmd. https://circleci.com/execution-environments/windows/ - **GPU** - Linux and Windows VMs with GPUs for AI, machine learning, gaming and other heavy computation. https://circleci.com/execution-environments/gpu/ - **Arm** - run jobs on Arm without maintaining your own hardware, and deploy to Arm targets such as AWS Graviton. https://circleci.com/execution-environments/arm/ - **Self-hosted runner** - run selected jobs on machines you control. https://circleci.com/execution-environments/runner/ ## Resources - Execution environments: https://circleci.com/execution-environments/ - Build images: https://circleci.com/product/build-images/ - Configuration reference: https://circleci.com/docs/reference/configuration-reference/ Source: https://circleci.com/execution-environments/ --- ## Self-Hosted Runners --- title: "CircleCI self-hosted runner" description: "Fast and secure CI/CD on infrastructure you control, orchestrated by CircleCI cloud." url: "https://circleci.com/execution-environments/runner/" --- # Self-Hosted Runners > Fast and secure CI/CD on your infrastructure. Automate your CI/CD workflows on > machines you control. Self-hosted runners let a job run on your own virtual machines, Kubernetes cluster, embedded hardware or custom compute, while CircleCI cloud continues to orchestrate the pipeline. Runners autoscale to match demand. ## Why Teams Use Them - **Data security and compliance** - sensitive data stays inside the network, reachable through IP restrictions and IAM controls. - **Cost management** - resource-intensive jobs run on capacity you already own. - **Infrastructure flexibility** - unusual hardware, pre-installed licensed software, and private network access. ## Resources - Self-hosted runner: https://circleci.com/execution-environments/runner/ - Runner documentation: https://circleci.com/docs/guides/execution-runner/runner-overview/ - Runner API: https://circleci.com/docs/guides/execution-runner/runner-api/ - Autoscaling: https://circleci.com/product/auto-scaling/ Source: https://circleci.com/execution-environments/runner/ --- ## Scale and Autoscaling --- title: "CI/CD that scales from startup to enterprise - CircleCI" description: "Dynamically scale compute to match demand, with job-level resource control and usage analytics." url: "https://circleci.com/product/auto-scaling/" --- # Scale and Autoscaling > CI/CD that scales with your business. Autoscaling adjusts self-hosted runner capacity in real time, on your cloud infrastructure or Kubernetes cluster, so queues drain without anyone provisioning machines by hand. ## Key Features - Flexible compute: containers, GPU machines and Arm processors across many resource classes. - Job-level resource control, tuning CPU and memory per job for performance and cost. - Parallelism that scales out, distributing jobs to clear bottlenecks. - Usage analytics through the dashboard and the usage API, to see where credits go. - Intelligent caching, which cuts both build time and the compute needed to serve it. ## Resources - Autoscaling: https://circleci.com/product/auto-scaling/ - Concurrency and parallelism: https://circleci.com/docs/guides/optimize/concurrency/ - Usage data: https://circleci.com/docs/guides/insights/usage/ Source: https://circleci.com/product/auto-scaling/ --- ## Build Optimization --- title: "The fastest CI/CD for high-performance teams - CircleCI" description: "Parallelism, caching, test splitting and smart reruns to run pipelines in minutes, not hours." url: "https://circleci.com/product/build-optimization/" --- # Build Optimization > Run pipelines in minutes, not hours. ## Key Features - **Job parallelism** - split a job across many containers and run thousands of tests at once. - **Test splitting** - divide a test suite by timing data, name or file size so every container finishes together. - **Dependency caching** - cache dependencies between jobs to avoid redundant downloads and builds. - **Docker layer caching** - reuse unchanged image layers instead of rebuilding an image each run. - **Smart test reruns and flaky test detection** - rerun only the failed tests, and identify tests that fail without a code change. - **Optimized machine images** - clean, current images that avoid provisioning overhead. ## Resources - Build optimization: https://circleci.com/product/build-optimization/ - Caching dependencies: https://circleci.com/docs/guides/optimize/caching/ - Test splitting: https://circleci.com/docs/guides/optimize/parallelism-faster-jobs/ - Docker layer caching: https://circleci.com/docs/guides/optimize/docker-layer-caching/ Source: https://circleci.com/product/build-optimization/ --- ## Metrics and Insights --- title: "Drive CI performance with actionable insights - CircleCI" description: "Turn pipeline data into performance gains and cost savings." url: "https://circleci.com/product/analytics-insights/" --- # Metrics and Insights > Turn pipeline data into performance gains and cost savings, with insights that > show exactly what to optimize next. ## Key Features - **Performance dashboard** - duration trends, queue times and success rates across projects, so regressions and bottlenecks are visible. - **Flaky test detection** - automatically identify unreliable tests and track failure patterns over time. - **Test and job timing data** - find the slowest jobs and the tests that dominate them. - **Usage analytics API** - granular credit and resource consumption data for custom reporting and spend optimization. ## Use Cases - Shortening feedback cycles by fixing the slowest jobs first. - Removing flakiness that erodes trust in the test suite. - Attributing engineering cost by workflow, job and user. ## Resources - Insights: https://circleci.com/product/analytics-insights/ - Insights documentation: https://circleci.com/docs/guides/insights/insights/ - Insights metric definitions: https://circleci.com/docs/reference/insights-glossary/ Source: https://circleci.com/product/analytics-insights/ --- ## Release Orchestration --- title: "Release orchestration - Control your software deployments - CircleCI" description: "Monitor deployments, roll out progressively, and roll back from a single dashboard." url: "https://circleci.com/solutions/release-orchestration/" --- # Release Orchestration > Orchestrate software releases with complete control. ## Key Features - **Deployment visibility** - every deployment in one dashboard, with real-time status. - **Progressive delivery** - canary deployments, controlled rollouts and rollback. - **Release management** - restore a previous version, scale or restart a component from the UI. - **Automated governance** - deployment policies, approval workflows, compliance checks and role-based access control. - **End-to-end traceability** - commit to production, with audit trails and release monitoring. ## Resources - Release orchestration: https://circleci.com/solutions/release-orchestration/ - Deploy documentation: https://circleci.com/docs/guides/deploy/deploy-overview/ - Rollback: https://circleci.com/docs/guides/deploy/rollback-a-project-using-the-rollback-feature/ Source: https://circleci.com/solutions/release-orchestration/ --- ## Security and Compliance --- title: "Secure CI/CD pipeline - Protect your software supply chain - CircleCI" description: "Enterprise-grade security controls, automated compliance checks and supply chain protection at every stage of delivery." url: "https://circleci.com/solutions/security-compliance/" --- # Security and Compliance > Deploy with confidence using enterprise-grade security controls, automated > compliance checks, and comprehensive supply chain protection at every stage of > delivery. ## Key Features - **Secrets management** - environment variables and contexts, encrypted at rest and injected at runtime. - **Granular access control** - restrict who can use a context, approve a job or deploy to an environment. - **Isolated, ephemeral environments** - each job runs in a fresh, network-isolated environment that is destroyed afterwards. - **Policy-as-code** - define and enforce security policies across the pipeline, from code quality to deployment approvals. - **Automated scanning** - vulnerability, dependency and infrastructure scanning as pipeline steps. - **Security gates** - block a deployment that fails a check. - **Audit trails** - a transparent record of every deployment, with real-time alerts. - **SOC 2 compliance** - independently audited controls. ## Resources - Security and compliance: https://circleci.com/solutions/security-compliance/ - Security overview: https://circleci.com/security/ - Contexts: https://circleci.com/docs/guides/security/contexts/ - OpenID Connect tokens: https://circleci.com/docs/guides/security/openid-connect-tokens/ - Config policies: https://circleci.com/docs/guides/security/config-policy-management-overview/ Source: https://circleci.com/solutions/security-compliance/ --- ## Orbs --- title: "CircleCI Orbs - reusable configuration packages" description: "Condense repeated pieces of config into a single line with reusable, shareable packages." url: "https://circleci.com/orbs/" --- # Orbs > Accelerate application development with reusable config. Condense repeated > pieces of code into a single line with orbs. An orb is a reusable package of YAML configuration, made up of commands, jobs and executors. Orbs cut the boilerplate out of a config file and standardize how an organization integrates a third-party tool. ## Key Features - Reusable commands, jobs and executors, versioned and published like a library. - A public registry of open source orbs across artifacts, build, code analysis, containers, deployment, security, testing, Kubernetes, languages and monitoring. - Private orbs, exclusive to one organization, for internal standards. - The Orb Development Kit, with automated testing and publishing on CircleCI. ## Resources - Orbs: https://circleci.com/orbs/ - Orb registry: https://circleci.com/developer/orbs - Orb introduction: https://circleci.com/docs/guides/reuse/orb-intro/ - Orb authoring: https://circleci.com/docs/guides/reuse/orb-author/ Source: https://circleci.com/orbs/ --- ## Integrations --- title: "CircleCI integrations" description: "Build your ideal toolchain with integrations across source control, cloud, containers, security, testing and observability." url: "https://circleci.com/integrations/" --- # Integrations > Accelerate your DevOps practices with CircleCI integrations. Build your ideal > toolchain. ## Categories Artifacts and registries, build, cloud platform, code analysis, collaboration, containers, deployment, infrastructure automation, Kubernetes, language and framework, monitoring, notifications, reporting, security, and testing. ## Named Integrations - **Source control** - GitHub, GitLab, Bitbucket. - **Cloud platforms** - AWS, Azure, Google Cloud, Heroku. - **Container registries** - Amazon ECR, Azure ACR, Google Artifact Registry, Docker Hub. - **Kubernetes** - Kubernetes, Helm, EKS, GKE. - **Observability** - Datadog, New Relic, Honeycomb, Coralogix, LogDNA. - **Security** - Anchore, Aqua Security, GitGuardian, Lacework, Prisma Cloud. - **Testing** - Cypress, Sauce Labs, Ghost Inspector, k6, LambdaTest. - **Notifications** - Slack, Microsoft Teams, and webhooks to anything else. ## Resources - Integrations: https://circleci.com/integrations/ - GitHub: https://circleci.com/integrations/github/ - GitLab: https://circleci.com/integrations/gitlab/ - Bitbucket: https://circleci.com/integrations/bitbucket/ - Webhooks: https://circleci.com/docs/guides/orchestrate/outbound-webhooks/ Source: https://circleci.com/integrations/ --- ## Configuration and Core Concepts --- title: "CircleCI concepts" description: "How a CircleCI pipeline is configured: pipelines, workflows, jobs, steps, contexts and data persistence." url: "https://circleci.com/docs/guides/about-circleci/concepts/" --- # Configuration and Core Concepts > CircleCI believes in configuration as code. A single file called `config.yml` > orchestrates your entire CI/CD process. The file lives at `.circleci/config.yml` in the repository root. Its components, in order of granularity: - **Pipeline** - the entirety of the configuration, triggered by a commit, a schedule, an API call or a webhook. - **Workflows** - orchestrate multiple jobs, in sequence, in parallel, or gated on approval. - **Jobs** - run a series of steps in a single executor and resource class. - **Steps** - run commands and shell scripts: install dependencies, run tests, deploy. ## Related Concepts - **Contexts** - name/value environment variables shared across projects and injected at runtime, with access restricted to chosen groups. - **Concurrency** - multiple jobs running at the same time. Distinct from parallelism, which splits one job's tests across containers. - **Data persistence** - artifacts persist outputs for months; caches store dependencies to speed up later jobs; workspaces pass data between jobs in one workflow. - **Docker layer caching** - reuses unchanged image layers across runs. - **Dynamic configuration** - a pipeline that generates and continues into further configuration at run time. - **Matrix jobs** - run one job repeatedly across a set of parameter values. ## Resources - Concepts: https://circleci.com/docs/guides/about-circleci/concepts/ - Configuration reference: https://circleci.com/docs/reference/configuration-reference/ - Introduction to YAML configuration: https://circleci.com/docs/guides/getting-started/introduction-to-yaml-configurations/ - Pipelines: https://circleci.com/docs/guides/orchestrate/pipelines/ - Dynamic configuration: https://circleci.com/docs/guides/orchestrate/dynamic-config/ Source: https://circleci.com/docs/guides/about-circleci/concepts/ --- ## Developer Tools and APIs --- title: "CircleCI developer tools" description: "CLI, editor extensions, prebuilt images, and the REST API." url: "https://circleci.com/developer" --- # Developer Tools and APIs > Central resource for APIs, CLI tools, Docker images, and integration assets. ## Key Features - **CircleCI CLI** - validate configuration, run jobs locally, manage contexts and orbs, and host a local MCP server. https://circleci.com/docs/guides/toolkit/local-cli/ - **VS Code extension** - view, manage and debug pipelines from the editor. https://circleci.com/docs/guides/toolkit/vs-code-extension-overview/ - **Convenience images** - maintained Docker images for common languages and toolchains. https://circleci.com/developer/images - **Orb registry** - reusable configuration packages. https://circleci.com/developer/orbs - **REST API** - API v3 is the current version and the one to use for new integrations. https://circleci.com/docs/api/v3 (markdown: https://circleci.com/docs/api/v3/index.md) - **API tokens** - personal and project-scoped tokens, plus OAuth 2.0 with dynamic client registration. https://circleci.com/docs/guides/toolkit/managing-api-tokens/ - **Webhooks** - outbound notifications on pipeline, workflow and job events. https://circleci.com/docs/guides/orchestrate/outbound-webhooks/ Source: https://circleci.com/developer --- ## CircleCI Server --- title: "CircleCI Server - CI/CD on your own infrastructure" description: "The power of CircleCI, on-prem or in your private cloud, installed on Kubernetes you manage." url: "https://circleci.com/pricing/server/" --- # CircleCI Server > The power of CircleCI, on-prem or in your private cloud. CircleCI Server is installed on a Kubernetes cluster you manage - GKE, EKS or native Kubernetes - behind your firewall or on your own hardware, with an air-gapped installation available. ## Key Features - All information stays inside your network, for data residency and security requirements. - Full administrative control, including org-wide guardrails through config policies. - Unlimited build minutes on capacity you provide. - Designed for heavy workloads inside private networks. ## Resources - CircleCI Server: https://circleci.com/pricing/server/ - Server administration: https://circleci.com/docs/ - Server versions: listed in https://circleci.com/docs/llms.txt Source: https://circleci.com/pricing/server/ --- ## Pricing --- title: "CircleCI pricing" description: "Free, Performance and Scale plans, priced in credits." url: "https://circleci.com/pricing/" --- # Pricing > Credits are the currency of CircleCI. Credits are purchased up-front and are > used to pay for CircleCI platform usage in real time. Usage covers active users, compute time by resource class, add-on features and overage. Plan details change, so treat the pricing page as authoritative. ## Plans - **Free** - $0/month. 30,000 credits per month, 5 active users, 30x concurrency. Credits expire monthly. - **Performance** - from $15/month. 30,000 free credits per month, additional credits in bulk, extra users per seat, 80x concurrency, larger resource classes, optional business-hours support. Paid credits roll over monthly and expire after a year. - **Scale** - custom, billed annually. Custom credit allocation, unlimited concurrency, the largest resource classes, GPU access, enterprise controls and optional 24/7 support. - **Server** - self-hosted, licensed separately, with user seats included. ## Resources - Pricing: https://circleci.com/pricing/ - Build your plan: https://circleci.com/pricing/build-your-plan/ - Price list: https://circleci.com/pricing/price-list/ - Server pricing: https://circleci.com/pricing/server/ - Support plans: https://circleci.com/support/plans/ Source: https://circleci.com/pricing/ --- ## Further Reading - Concise index for LLMs: https://circleci.com/llms.txt - Documentation index for LLMs: https://circleci.com/docs/llms.txt - Documentation: https://circleci.com/docs/ - API v3 reference: https://circleci.com/docs/api/v3 - API v3 reference as markdown: https://circleci.com/docs/api/v3/index.md, one file per entity, all listed at https://circleci.com/docs/api/v3/llms.txt - Developer hub: https://circleci.com/developer - Blog: https://circleci.com/blog/ - Changelog: https://circleci.com/changelog/ - Customer stories: https://circleci.com/customers/ - Support plans: https://circleci.com/support/plans/ - Comparisons: https://circleci.com/compare/github-actions-vs-circleci/, https://circleci.com/compare/jenkins-vs-circleci/, https://circleci.com/compare/harness-vs-circleci/, https://circleci.com/compare/buildkite-vs-circleci/, https://circleci.com/compare/bitrise-vs-circleci/