CircleCI Logo
Navigation Menu Icon

Chunk overview and setup Beta

Language Icon 4 days ago
Cloud
Chunk is currently in beta. There are no extra costs during beta. Chunk uses CircleCI credits and your AI model provider tokens. Chunk tasks will be a paid feature when generally available.
Feedback or feature requests? Submit them on our Ideas board where you can also see existing feature requests and vote on them.

Chunk by CircleCI assists with CI/CD related tasks through a natural language chat interface and task scheduling.

  • Use the Chunk chat UI to get help with any aspect of your project.

  • Assign Chunk tasks to proactively manage your CI/CD processes. For an example, see the Fix Flaky Tests guide.

How Chunk works

Chunk connects to your existing CircleCI pipelines and analyzes both your build history and repository code. It uses this analysis to understand how your tests, configurations, and dependencies behave.

Chunk is equipped with specialized skills to help you maintain and improve your software:

Fix flaky tests

Identify and resolve known flaky tests in your codebase.

Extend test coverage

Analyze your codebase and add new tests for untested or under-tested code.

Fix bugs

Detect and resolve bugs in your code.

Refactor code

Suggest improvements for better code maintainability.

Improve documentation

Add or enhance documentation for key functions and components.

Optimize build configs

Review and improve your CircleCI configuration for better performance and efficiency.

When you provide Chunk with a task or question, it applies the appropriate specialized skill to deliver targeted solutions. As your codebase evolves, Chunk helps ensure your software remains validated and your codebase stays healthy over time.

Model providers

Chunk supports four model providers. Three providers require you to bring your own API key. One provider is managed by CircleCI and requires no API key.

Provider API key required Notes

CircleCI (Powered by Anthropic)

No

CircleCI provides the API key. You receive 400,000 tokens per day. The token limit resets at 12:00 UTC. This is the default option.

Anthropic

Yes

Bring your own Anthropic API key. Your source code is not stored or used for training purposes by CircleCI.

OpenAI

Yes

Bring your own OpenAI API key. Your source code is not stored or used for training purposes by CircleCI.

Amazon Bedrock

Yes

Bring your own AWS credentials. Only Anthropic Claude models are supported on Amazon Bedrock. Your source code and data do not leave your AWS environment.

Your credentials are stored securely in your organization’s circleci-agents context once saved.

Set up Chunk

The following sections guide you through the Chunk setup process. Once setup is complete, you can chat with Chunk for help with projects and assign Chunk tasks to proactively manage your CI/CD processes.

Prerequisites

Ensure you have the following in place before you get started:

  • The CircleCI GitHub App installed in your organization. Check Organization Settings > VCS Connections. Chunk needs the GitHub App to recommend fixes and open pull requests.

  • The Allow Chunk tasks option enabled for your organization. Navigate to Organization Settings > Advanced and toggle on Allow Chunk tasks.

  • A model provider API key, if you are not using the default CircleCI (Powered by Anthropic) option. See the Model providers section for details on each provider.

If you are using OpenAI, you also need to:

If you are using Amazon Bedrock, you also need:

  • An active AWS account with Amazon Bedrock enabled.

  • Access granted to an Anthropic Claude model in the AWS Bedrock console. You must request this access before Chunk can invoke the model.

  • An AWS bearer token (API key) with the bedrock:InvokeModel IAM permission.

  • The AWS region where your chosen Anthropic Claude model is available, for example us-east-1.

Setup

Once you meet the prerequisites, set up Chunk as follows:

  1. In the CircleCI web app, select your organization.

  2. Select Chunk from the bottom of the sidebar.

  3. Select Set up Chunk.

    Chunk setup modal
    Figure 1. Set up Chunk for your organization

  4. You should see a checkmark to confirm the GitHub App is installed for your organization. If not, select Install CircleCI GitHub App to install it now.

  5. Select your AI model provider from the Select your AI Model dropdown. The available options are:

    • CircleCI (Powered by Anthropic): No API key required. This is the default option.

    • Anthropic: Requires your own Anthropic API key.

    • OpenAI: Requires your own OpenAI API key.

    • Amazon Bedrock: Requires your own AWS credentials.

  6. If you selected a provider that requires an API key, enter your credentials. See the Provider setup details section below for the specific fields required for each provider.

  7. Select Next to save your credentials. They are stored securely in your organization’s circleci-agents context.

  8. Complete the remaining onboarding steps to finish setting up Chunk.

Once Chunk is set up, use the chat interface to instruct Chunk to help you with your CI/CD tasks. Describe your task and tell Chunk which project, repository, and branch to work within.

For a guide to using built-in tasks, see the Fix Flaky Tests guide.

Provider setup details

  • CircleCI (Powered by Anthropic)

  • Anthropic

  • OpenAI

  • Amazon Bedrock

No additional setup is required. CircleCI provides the API key. Select CircleCI (Powered by Anthropic) from the dropdown and then select Next.

Your free beta allowance includes 400,000 tokens per day. The token limit resets at 12:00 UTC.

Enter your Anthropic API key. You can generate a key in the Anthropic console.

Set up your model provider API key
Figure 2. Set up your model provider API key

Enter your OpenAI API key. You can generate a key in the OpenAI platform.

You need to enter three values:

Field Example value Description

AWS bearer token

AKIA…​

Your AWS API key. Use an IAM user or role with the bedrock:InvokeModel permission. Do not use root account credentials.

AWS region

us-east-1

The region where your Anthropic Claude model is available.

Model

us.anthropic.claude-sonnet-4-20250514-v1:0

The Anthropic Claude inference profile ID, including the region prefix.

The model ID must include a region prefix, for example us., eu., or ap.. The correct format is:

<region-prefix>.anthropic.<model-name>

These are cross-region inference profile IDs, which AWS uses to route requests for higher availability. For the full list, see Supported regions and models for inference profiles in the AWS documentation.

Anthropic Claude models only. Chunk on Amazon Bedrock supports Anthropic Claude models exclusively. Other Bedrock providers such as Amazon Titan, Meta Llama, and Mistral are not supported.

Recommended models:

  • Claude Sonnet. Best balance of performance and speed for code tasks. This is the recommended default.

  • Claude Haiku. Fastest and most cost-efficient.

  • Claude Opus. Most capable, and best for complex, multi-file analysis.

For a full list of supported Anthropic model IDs, see Supported foundation models in Amazon Bedrock in the AWS documentation.

Supported regions:

Not all Claude models are available in all AWS regions. Check model-to-region availability in the Model support by AWS Region page in the AWS documentation. Popular regions for Anthropic Claude on Bedrock include:

  • us-east-1 US East (N. Virginia), widest model availability.

  • us-west-2 US West (Oregon).

  • eu-west-1 Europe (Ireland).

  • ap-southeast-1 Asia Pacific (Singapore).

Request model access:

Amazon Bedrock requires you to explicitly request access to each model before you can invoke it. If you skip this step, Chunk will fail when calling the model.

  1. Sign in to the AWS Management Console and navigate to Amazon Bedrock.

  2. In the left sidebar, select Model access.

  3. Find the Anthropic Claude model you want to use and select Request access.

  4. Wait for access to be granted. Some Anthropic models require you to submit a use case before access is approved.

Access is granted per region. If you switch AWS regions, you need to request model access again for that region.

Tear down

If you need to tear down Chunk for your organization, delete your model provider API key from the circleci-agents context as follows:

  1. In the CircleCI web app, select your organization and then select Chunk from the bottom of the sidebar.

  2. Select the Settings button at the top of the window (the cog icon).

  3. Under "Model Provider API Keys", select Edit in contexts. You will be redirected to your organization’s Contexts page.

  4. Locate the circleci-agents context. Select it by name to open the context page and view the stored environment variables.

  5. Locate your model provider API key environment variable and select it using the radio button.

  6. Select Delete to delete the environment variable. You will be prompted to confirm the deletion.

CircleCI (Powered by Anthropic) users. If you are using the CircleCI-managed provider, there is no API key stored in your context. To remove Chunk access, disable the Allow Chunk tasks toggle in Organization Settings > Advanced.

Fix failed builds with Chunk

Chunk provides contextual fix buttons directly in the CircleCI web app. These buttons appear when a build, job, workflow, or step fails. Selecting a fix button opens Chunk with the failure context already filled in.

You do not need to navigate to Chunk manually or describe the failure yourself. Chunk reads the failure details and starts working on a fix.

GitHub only. Chunk fix buttons are available for circleci and github organizations with the CircleCI GitHub App installed. To check your organization type, see the Users, Organizations, and Integrations page.

Fix buttons overview

The following fix buttons are available:

  • Fix error (Beta)

  • Fix job (Beta)

  • Fix workflow (Beta)

Fix error (Beta) appears in the step output header on the job page, next to Explain error.

Fix error (Beta) button in step output
Figure 3. Fix error (Beta) button in step output

Fix job (Beta) appears:

  • In the job header on the job page.

    Fix job (Beta) button in the job header
    Figure 4. Fix job (Beta) button in the job header

  • On hover, next to a failed job in the pipeline list.

    Fix job (Beta) button on hover in the pipeline list
    Figure 5. Fix job (Beta) button in the pipeline list

Fix workflow (Beta) appears:

  • Next to a failed pipeline row in the pipeline list, to the left of the ellipsis icon (Ellipsis icon).

    Fix workflow (Beta) button on the pipeline list
    Figure 6. Fix workflow (Beta) button in the pipeline list

  • In the workflow header on the workflow page.

    Fix workflow (Beta) button in the workflow header
    Figure 7. Fix workflow (Beta) button in the workflow header

Set up Chunk from a fix button

If your organization has not set up Chunk, you can start the setup process directly from any fix button.

When you click a fix button and Chunk is not configured for your organization, the Chunk setup flow starts automatically. You do not need to navigate to the Chunk page first.

  1. Select any fix button on a failed build, job, workflow, or step.

  2. The Chunk intro modal appears. Select Get Started.

  3. Follow the on-screen steps to install the CircleCI GitHub App and enter your AI model provider API key. See Set up Chunk for details on prerequisites and API key requirements.

  4. Select Next to complete setup. The Chunk task drawer opens with the failure context from the button you clicked.

After setup is complete, clicking any fix button opens the Chunk task drawer directly, with failure context pre-filled.

Chunk environment setup

To improve verification success, create an "agent environment" CircleCI YAML file. Copy the environment setup sections from your existing CircleCI configuration file into a dedicated file for Chunk.

  • Name the file cci-agent-setup.yml and save it to your .circleci directory on your default branch.

  • The file needs to include a single workflow with a single job named cci-agent-setup. The cci-agent-setup job needs to set up your environment for Chunk to use. You do not need to include steps to run tests. This file is purely for environment setup.

Example cci-agent-setup.yml
version: 2.1
workflows:
  main:
    jobs:
      - cci-agent-setup
jobs:
  cci-agent-setup:
    docker:
    - image: cimg/python:3.12
    - image: cimg/postgres:15.3
    steps:
      - checkout
      - run:
          name: Hello World
          command: |
            echo "Hello, World!"
      # insert more environment setup here

Chunk supports all standard CircleCI configuration options, including executors, resource classes, caching, contexts, environment variables, service containers, and orbs. If it works in your .circleci/config.yml, it works in cci-agent-setup.yml. For a complete reference, see the Configuration Reference.

Instruct Chunk to use your environment

When scheduling a task, store your cci-agent-setup.yml in your repository and Chunk will pick it up automatically.

When using the chat interface, use the environment selector below the chat text field to set up your environment. If you keep the Default environment selected, Chunk will look for a cci-agent-setup.yml file in the root of your repository. If you want to name this file differently, create a custom environment and provide Chunk with the name of the file.

You can also add secrets (environment variables) to Chunk’s environment here if needed. These secrets will be added to a context named chunk-<your-environment-name>.

Create an environment for Chunk to use
Figure 8. Creating an environment for Chunk to use

Example cci-agent-setup.yml files

The following examples show how to set up an environment for Chunk for a variety of use cases:

  • Python

  • Caching and contexts

  • Multiple services

  • Resource classes and machine

version: 2.1
workflows:
  cci-agent-setup:
    jobs:
      - cci-agent-setup
jobs:
  cci-agent-setup:
    docker:
      - image: cimg/python:3.12
      - image: cimg/postgres:15.3
    steps:
      - checkout
      - run:
          name: Install dependencies
          command: |
             pip install -r requirements.txt
version: 2.1
workflows:
  cci-agent-setup:
    jobs:
      - cci-agent-setup:
          context:
            - my-team-context  # Includes any secrets/env vars from this context
jobs:
  cci-agent-setup:
    docker:
      - image: cimg/node:18.0
    steps:
      - checkout
      - restore_cache:
          keys:
            - v1-dependencies-{{ checksum "package-lock.json" }}
      - run:
          name: Install dependencies
          command: npm install
      - save_cache:
          paths:
            - node_modules
          key: v1-dependencies-{{ checksum "package-lock.json" }}
version: 2.1
workflows:
  cci-agent-setup:
    jobs:
      - cci-agent-setup
jobs:
  cci-agent-setup:
    docker:
      - image: cimg/ruby:3.2
      - image: cimg/postgres:15.3
        environment:
          POSTGRES_USER: circleci
          POSTGRES_DB: test_db
      - image: redis:7.0
    steps:
      - checkout
      - run:
          name: Wait for DB
          command: dockerize -wait tcp://localhost:5432 -timeout 1m
      - run:
          name: Install dependencies
          command: bundle install
      - run:
          name: Setup database
          command: bundle exec rake db:setup
version: 2.1
workflows:
  cci-agent-setup:
    jobs:
      - cci-agent-setup
jobs:
  cci-agent-setup:
    machine:
      image: ubuntu-2204:2024.01.2
    resource_class: large
    steps:
      - checkout
      - run:
          name: Install dependencies
          command: |
            sudo apt-get update
            sudo apt-get install -y build-essential

Environment variables and contexts

Project environment variables

Chunk automatically has access to any environment variables configured at the project level in CircleCI. You do not need to recreate or reference these. They are already available.

Contexts

If you are using CircleCI contexts to manage secrets or environment variables, you must include the context in your cci-agent-setup job, as shown in the caching and contexts example above. Chunk will have access to all variables from that context. You do not need to manually recreate them.

Configuring Chunk’s environment when using the chat interface

When using the Chunk chat interface, you can tell Chunk which project, repository, and branch to work on. You can also set up Chunk’s environment using the Environment selector. Use this to give Chunk access to any secrets needed, or to provide Chunk with the name of your agent .yml file if different from the default cci-agent-setup.yml.

Testing your environment setup

To build and iterate on Chunk’s environment, follow these steps:

  1. Navigate to Organization Settings  Chunk Tasks.

  2. Identify your desired agent task.

  3. Select the ellipsis icon (Ellipsis icon) and select Chunk Environment.

This page lets you run the contents of your cci-agent-setup.yml file on a specific branch and immediately see the results. Use the Custom button to submit a task to Chunk and see the results.

Merge the cci-agent-setup.yml file to your default branch when the results are satisfactory.

Additional guidance for Chunk

To improve Chunk’s ability to run tests and produce fixes aligned with your stylistic and architectural preferences, you can include instructions in a markdown file. Name the file claude.md or agents.md and place it in the root of your repository. Chunk picks this up automatically.

Troubleshooting

I cannot see the Chunk option in the sidebar

If you do not see Chunk Chunk icon in the sidebar, you may not have the Allow Chunk tasks option enabled. Navigate to Organization Settings  Advanced and toggle on Allow Chunk tasks.

Allow Chunk tasks
Figure 9. Organization settings > Advanced > Allow Chunk tasks

I cannot get my OpenAI organization verified

If organization verification is not possible, you can bypass this requirement by adding an environment variable to your circleci-agents context as follows:

  1. In the CircleCI web app, go to Organization Settings > Contexts.

  2. Use the search to find the circleci-agents context. Select it by name to open configuration options.

  3. Scroll down to the "Environment variables" section.

  4. Select Add environment variable and enter the following:

    • Under "Environment variable name", enter CCI_AGENT_OPENAI_MODEL.

    • Under "Value", enter gpt-5-nano.

Invalid OpenAI model specified

If you get the following error:

Invalid OpenAI model specified. Please check the model name and ensure it is available for your account.

You need to make sure your organization has GPT-5 access. To verify this in the OpenAI Platform, follow these steps:

  1. Switch to the project you want to check using the top left dropdown.

  2. Go to Settings > Limits in the left-hand menu. This page shows the models and rate limits for your project. gpt-5 will be listed if you have access.

Amazon Bedrock authentication error or 401

Your AWS bearer token is invalid or has expired. Regenerate the token in AWS IAM and update it in the circleci-agents context in Organization Settings > Contexts.

Amazon Bedrock access denied or 403 on model invocation

You have not requested access to the Anthropic Claude model in the Bedrock console, or access has not yet been granted. Navigate to the AWS Management Console, go to Amazon Bedrock > Model access, and confirm the model is enabled.

Amazon Bedrock model not found or 404

The model ID is incorrect or is missing the required region prefix, for example us.. Confirm the format is <region-prefix>.anthropic.<model-name> and verify that your chosen AWS region supports the model. See the Model support by AWS Region page in the AWS documentation.

Chunk runs but produces no output when using Amazon Bedrock

The IAM credentials attached to your AWS API key may lack the bedrock:InvokeModel permission. Review the IAM policy attached to your API key in the AWS IAM console.

High latency or timeouts when using Amazon Bedrock

Consider using a different region prefix in your inference profile ID to route requests to a less congested region. See the Provider setup details section for guidance on supported regions.

Frequently asked questions

Does CircleCI use my data to train AI models?

No. CircleCI does not store your source code or use it for training purposes. Chunk processes your code temporarily to generate fixes but does not retain or share this information with model providers for training.

How long are Chunk’s logs stored?

Chunk’s logs are stored by CircleCI for 90 days. The 90-day retention period applies to all organizations, regardless of your plan’s standard data retention policy. After 90 days, logs are automatically deleted.

Can I use any Anthropic Claude model on Amazon Bedrock?

Chunk supports all Anthropic Claude models available on Amazon Bedrock. Other Bedrock providers such as Amazon Titan, Meta Llama, and Mistral are not supported. For the full list of supported model IDs, see the Supported foundation models in Amazon Bedrock page in the AWS documentation.

What happens when I reach the 400,000 token daily limit for CircleCI (Powered by Anthropic)?

The token limit resets at 12:00 UTC each day. If you need more tokens, switch to a provider that requires your own API key, such as Anthropic, OpenAI, or Amazon Bedrock.

Next steps

Assign a Chunk task to proactively fix your flaky tests. See the Fix Flaky Tests guide for more information.