Start Building for Free


2 weeks ago27 min read
Server v4.x
Server v3.x
On This Page


Does CircleCI look at my code?

CircleCI employees never look at your code without permission. If you have requested support, a support engineer may ask permission to look at your code to help you debug the problem.

See the CircleCI Security policy for more details.

Can I use CircleCI without creating base images?

Yes, CircleCI provides a selection of "convenience images" for use with the Docker executor. For a full list, along with usage instructions, visit the CircleCI Developer Hub and the CircleCI images guide.

For the machine executor, see the available machine images list.

For an introduction to execution environments and images, see the Introduction to execution environments.

Can I request new features?

Yes, you can visit CircleCI’s Ideas page to request new features, or view features that have already been requested. To request a new feature, you will first need to select a category from the Give Feedback section.

When viewing requested features, you can sort by Trending, Top, and New, as well as filter by the following:

  • Under Review: CirlceCI is considering these feature requests.

  • Planned: CircleCI has planned to work on these feature requests in the future.

  • In Progress: CircleCI is currently working on these feature requests.

  • Complete: CircleCI has added these feature requests to its current offerings.


Can I migrate my existing CI/CD solution to CircleCI?

Yes, CircleCI offers migration guides for the following:

You can also visit the Migration introduction page for more information.

Host CircleCI

What are the differences between CircleCI’s hosting options?

  • Cloud - CircleCI manages the setup, infrastructure, security and maintenance of your services. You get instant access to new feature releases and automatic upgrades, alleviating the need for manual work on an internal system.

  • Server - You install and manage CircleCI, through a service like AWS or GCP. Server installations are behind a firewall that your team sets up and maintains according to your data center policy. You have full administrative control for complete customization and management of upgrades as new versions are released.

Is CircleCI available to enterprise customers?

Yes, CircleCI server is available for installation on AWS or GCP. See the CircleCI server v4.x overview for details and links to installation instructions. Contact us to discuss your requirements.


What operating systems does CircleCI support?

Which CPU architectures does CircleCI support?

CircleCI supports amd64 for Docker jobs, and both amd64 and Arm resources for machine jobs.

Can I use IPv6 in my tests?

You can use the Machine executor for testing local IPv6 traffic. Unfortunately, we do not support IPv6 internet traffic, as not all of our cloud providers offer IPv6 support.

Hosts running with machine executor are configured with IPv6 addresses for eth0 and lo network interfaces.

You can also configure Docker to assign IPv6 address to containers, to test services with IPv6 setup. You can enable it globally by configuring docker daemon like the following:

      # The image uses the current tag, which always points to the most recent
      # supported release. If stability and determinism are crucial for your CI
      # pipeline, use a release date tag with your image, e.g. ubuntu-2004:202201-02
      image: ubuntu-2004:current
      - checkout
      - run:
          name: enable ipv6
          command: |
            cat <<'EOF' | sudo tee /etc/docker/daemon.json
              "ipv6": true,
              "fixed-cidr-v6": "2001:db8:1::/64"
            sudo service docker restart

Docker allows enabling IPv6 at different levels: globally via daemon config like above, with docker network create command, and with docker-compose.


Can orbs be made private?

Private orbs are available on any of our current plans.

What is the difference between commands and jobs?

Both commands and jobs are elements that can be used within orbs.

Commands contain one or many steps, which contain the logic of the orb. Commands generally execute some shell code (bash).

Jobs are a definition of what steps/commands to run and the executor to run them in. Jobs invoke commands, and are orchestrated using workflows.

Can orbs be used on a private installation of CircleCI server?

Orbs can be used with installations of CircleCI server. For information on importing and using orbs for server, see the CircleCI server managing orbs page.

How can I report a bug or issue with a public orb?

All public orbs are open source projects. Issues, bug reports, or even pull requests can be made against the orb’s git repository. Public orb authors may opt to include a link to the git repo on the orb registry. If the git repo link is unavailable, contact support and we will attempt to contact the author. Alternatively, consider forking the orb and publishing your own version.

How do I use the latest version of an orb?

Orbs use semantic versioning, meaning if you set the major version (example: 3), you will receive all minor and patch updates, where if you statically set the version (example: 3.0.0), no updates will apply, this is the most deterministic and recommended method.

Author orbs

Is it possible to delete an orb I’ve created?

No. Orbs are public by default and immutable, once a version of an orb is published it can not be changed. This is done so users can reasonably expect a known version of an orb will behave the same on every run. Deleting an orb could potentially lead to a failing pipeline in any of its user’s projects.

Orbs can however be "Unlisted" from the Orb registry. Unlisted orbs still exist and are discoverable via the API or CLI, but will not appear in the Orb Registry results. This may be desired if for instance, an orb is no longer maintained.

circleci orb unlist <namespace>/<orb> <true|false> [flags]

How do I protect a user’s API tokens and other sensitive information?

Use the env_var_name parameter type for the API key parameter. This parameter type will only accept valid POSIX environment variable name strings as input. In the parameter description, it is best practice to mention to the user to add this environment variable.

If you are interested in reading more on this topic, visit the Environment variable name and Best practices pages.

How can I require a user to add an environment variable?

Create a parameter for the environment variable name, even if it is a statically named environment variable the user should not change. Then, assign it the correct default value. In the parameter description let the user know if this value should not be changed. Either way, consider instructing the user on how they can obtain their API key.

Consider validating required environment variables. See more in the Orb author best practices guide.

If you are interested in reading more on this topic, visit the Environment variable name and Best practices pages.

What language do I use to write an orb?

Orbs are packages of CircleCI YAML configuration.

CircleCI orbs package CircleCI reusable config, such as commands, which can execute within a given executor defined by either, the user if using a command within a custom job, or by the orb author if using a reusable job. The environment within which your logic is running may influence your language decisions.

What programming languages can I write my Command logic in?

POSIX compliant bash is the most portable and universal language. This is the recommended option when you intend to share your orb. Orbs do, however, come with the flexibility and freedom to run other programming languages or tools.


Bash is the preferred language as it is most commonly available among all available executors. Bash can (and should) be easily written directly using the native run command. The default shell on MacOS and Linux will be bash.


  - run:
    name: Check Ruby shell
    shell: ruby
    command: puts 'hi'


  - run:
    name: Check Node shell
    shell: node
    command: console.log('node')


  - run:
    name: Check Python shell
    shell: python3
    command: print('python')


This option is strongly discouraged wherever possible. Sometimes it may be necessary to fetch a remote binary file such as a CLI tool. These binaries should be fetched from a package manager or hosted by a VCS such as GitHub releases wherever possible. For example, installing Homebrew as a part of the AWS Serverless orb.

  - run:
    command: >
      curl -fsSL
      "" | bash
      /home/linuxbrew/.linuxbrew/bin/brew shellenv >> "$BASH_ENV"
    name: Install Homebrew (for Linux)

Should I create a command or a job?

The answer might be both, but it will heavily depend on the task you want to accomplish.

An orb command can be utilized by the user, or even the orb developer, to perform some action within a job. The command itself has no knowledge of the job it is within as the user could utilize it however they wish. A command may be useful, for example, to automatically install a CLI application or go a step further and install and authenticate.

A job defines a collection of steps and commands within a specific execution environment. A job is highly opinionated as it generally chooses the execution platform to run on and what steps to run. Jobs may offer a useful way to automate tasks such as deployments. A deployment job may select a certain execution platform that is known, such as python, and automatically checkout the users code, install a CLI, and run a deployment command, all with little to no additional configuration required from the user.

Self-hosted runner

What is a CircleCI task vs. a job?

A task is the smallest unit of work on CircleCI. If a job has parallelism of one, it is one task. If a job has parallelism = n and n > 1, then the job creates n tasks to execute.

What is a runner resource class? What is a resource class token?

A resource class is a label to match your CircleCI job with a type of runner (or container runner) that is identified to process that job. The first part of the resource class is your organization’s namespace. For example, a CircleCI resource class could be circleci/documentation.

Resource classes help you identify a pool of self-hosted runners, which allow you to set up your configuration to send jobs to specific resources. For example, if you have multiple machines running macOS, and multiple machines running Linux, you could create resource classes for each of these, orgname/macOS and orgname/linux, respectively. At the job level in your .circleci/config.yml, you can associate which self-hosted runner resources to send a job to based on the resource class.

Every time you create a resource class, a resource class token is generated that is associated with the given resource class. This token is the method by which CircleCI authenticates that the resource class is valid. The resource class token only has access to claim tasks.

What is the security model for CircleCI’s self-hosted runners?

Machine runners let you choose the user that executes jobs when the self-hosted runner is installed. It is up to you to ensure this user only has permissions you are comfortable letting jobs use. The container runner installation page describes the security model for container runners.

How do I install dependencies needed for my jobs that use machine runners?

There are two main approaches available for installing dependencies:

  • Allow the jobs to install their own dependencies

This approach is the most flexible, but will require providing the jobs sufficient privileges to install tools or install the tools in a non-overlapping manner (eg. into the working directory).

  • Pre-install dependencies on the machine where the machine runner is installed

This approach is the most secure; however, this means that if the job’s dependencies change, the self-hosted runner machine must be reconfigured.

What connectivity is required?

In order to connect back to CircleCI to receive and execute jobs, outbound HTTPS connections to, are required.

How do caching, workspaces, and artifacts work with CircleCI’s self-hosted runners?

Caches, workspaces, and artifacts are methods you can implement to help persist data between jobs, and speed up builds. All three features are compatible with self-hosted runners.

Find out more about these concepts below:

You can also find out more on the Persisting data page.

If you would prefer to take complete control of artifact storage, CircleCI recommends you avoid the built-in steps and upload the artifacts directly to your chosen storage backend.

What are the best practices for managing state between jobs?

Machine runners are unopinionated about state between jobs. Machine runners can be configured to give each job a unique working directory and clean it up afterwards - but this is optional. And by default, nothing restricts the job from placing files outside of its working directory.

In general CircleCI recommends jobs rely on as little state as possible to improve their reproducibility. An effective way to accomplish this is to put cleanup steps at the start of a job so they are guaranteed to run regardless of what happened to a previous job.

How long do inactive self-hosted runners persist in the self-hosted runner inventory page?

If a self-hosted runner has not contacted CircleCI in 12 hours, it will not show up in the inventory page on the CircleCI web app.

Can I delete self-hosted runner resource classes?

Yes, self-hosted runner resource classes can be deleted through the CLI. Please be sure you want to permanently delete the resource class and its associated tokens, as this action cannot be undone.

circleci runner resource-class delete <resource-class> --force

Who can create, delete, and view self-hosted runner resource classes?

Organization admins in your VCS provider can create and delete self-hosted runner resource classes. Any organization user in your VCS provider that the resource class is associated with can view the resource class list through the CLI.

Can I delete runner resource class tokens?

Yes, runner resource class tokens can be deleted through the CLI. Please be sure you want to permanently delete the token as this action cannot be undone. Note this will not delete the resource class itself, only the token.

To get the list of tokens and their identifiers:

circleci runner token list <resource-class name>

To delete the token itself:

circleci runner token delete <token identifier>

Can I create additional runner resource class tokens?

Yes, additional runner resource class tokens for a specific runner resource class can be created through the CLI.

To create the token:

circleci runner token create <resource-class-name> <nickname>

Can jobs on forks of my OSS project use my organization’s self-hosted runners if the fork is not a part of my organization?

No, runner resource classes cannot be used by jobs that are not associated with the organization that owns the runner resource classes. Only forks of your OSS project that are a part of your organization may use the organization’s self-hosted runners.

Why did my test splitting job step error with circleci: command not found?

On self-hosted runners, circleci-agent is used for all commands in which you may use either circleci-agent or circleci on CircleCI cloud (such as test splitting and step halt commands). Please note, circleci is not to be confused with the local CircleCI CLI, and is simply an alias of circleci-agent.

If you would like to use the local CircleCI CLI in your self-hosted runner jobs, which can proxy test commands to circleci-agent, you can install the CLI via a job step. Install the CLI as a dependency on your machine for machine runner, or include it in a Docker image for container runner.

Container runner specific FAQs

This section answers frequently asked questions for CircleCI’s container runner.

Is there only one resource class allowed per container runner deployment?

No, you can use as many resource classes as you desire with your container runner deployment. At least one resource class is required in order to run a job successfully with container runner.

Does container runner use a pull or push based model?

Container runner uses a pull-based model.

Does container runner scale my Kubernetes cluster for me?

Container runner itself is its own deployment of a single replica set that does not currently require scaling. Container runner will not scale the Kubernetes cluster itself. It schedules work if there are available resources in the cluster.

You can use the queue depth API as a signal for cluster scaling.

Is there a limit for the number of concurrent tasks that container runner can handle?

Container runner will claim and schedule work up to your runner concurrency limit. Additionally, by default, container runner is configured with a limit of 20 tasks it will allow to be concurrently scheduled and running. This can be configured via Helm to be a different value if your runner concurrency allows for a value greater than 20. See the agent.maxConcurrentTasks parameter on the Container runner page.

An organization’s runner concurrency limit is shared with any existing machine self-hosted runners. If you do not know what your organization’s runner concurrency limit is, ask your point of contact at CircleCI, or submit a support ticket.

Can I build Docker images with container runner either via Remote Docker or Docker in Docker (DIND)?

See building container images for details.

Can I use something other than Kubernetes with container runner?

At this time, no. Kubernetes and Helm are required.

Does container runner require specific Kubernetes providers?

No, any Kubernetes provider can be used.

Does container runner need to sit within the cluster that it deploys pods to?

At this time, yes.

What platforms can you install container runner on?

amd64 and arm64 Linux for both container runner, and the pods that execute tasks.

Does container runner support arm64 Docker images?

Yes, container runner supports jobs that use either amd64 or arm64 Docker images, as well as Kubernetes clusters that use a mixture of amd64 and arm64 nodes. When using images built for a specific architecture, resource classes will need to be configured to target a node with that CPU architecture. Kubernetes provides several node labels automatically that are helpful in configuring the resource class pod specifications for a job to be deployed on the correct node. An example resource class configuration is shown in the example below. More information about these labels can be found in the Kubernetes documentation.

      <amd64 image resource class>:
         token: <amd64 resource class token>
            nodeSelector: # nodeSelector will cause this resource class to only create pods on nodes with the specified labels and values

      <arm64 image resource class>:
         token: <arm64 resource class token>

      <multiarchitecture image resource class>: # note no nodeSelector is defined for the multiarchitecture image resource class
         token: <multiarchitecture resource class token>

How do I uninstall container runner?

To uninstall the container-agent deployment, run:

$ helm uninstall container-agent

The command removes all the Kubernetes objects associated with the chart and deletes the release.

Does container runner replace the existing self-hosted runner from CircleCI?

No, container runner is meant to complement machine runners. With container runner and machine runners, CircleCI users have the flexibility to choose the execution environment they desire (Container vs. Machine) just like they are afforded on CircleCI’s cloud platform.

What happens if I increase agent.ReplicaCount?

Currently, Kubernetes will attempt to deploy an additional container runner. This is not recommended at this time as this scenario is untested and may not work as expected.

If there are two container runners deployed to a single Kubernetes cluster, how does the agent.maxConcurrentTasks parameter work?

The agent.maxConcurrentTasks parameter applies to each agent individually. However, multiple container runner deployments per Kubernetes cluster is not recommended at this time.

How do I upgrade to the latest Helm chart?

Updates to the Helm chart can be applied via:

$ helm repo update
$ helm upgrade container-agent

How is container runner versioned?

Container runner uses semantic versioning for both the container runner application as well as the Helm chart used for installation. The container runner image provides a floating tag for each major and minor version, that points to the most recent release of each, as well as a fully qualified tag that points to a specific patch release for a minor version.

How is a version of container runner supported?

The container runner application promises backwards compatibility for releases within the same major version, as well as vulnerability and bug support for the most recent minor version. The Helm chart for container runner promises backwards compatibility with the values file within the same major version.

What are the security considerations for container runner?

Just like a machine runner, a container runner allows users to run arbitrary code in the infrastructure where container runner is hosted, meaning a bad actor could potentially use it as a method to gain knowledge of internal systems. Ensure you are following all best practices for security to mitigate this risk.

How can an IAM role be used to authorize pulling images from ECR?

An IAM role can be associated with the service account used for the container runner by following the AWS documentation. If an image in a job configuration specifies AWS credentials, those credentials will be used instead of the IAM role attached to the container runner service account. See the Container runner documentation for more details about the container runner service account.

What if I want to run my CI job within a container, but do not want to use Kubernetes?

If you would like to run your CI job within a container, but do not want to use Kubernetes, you can use a machine runner with Docker installed.

Machine runner specific FAQs

This section answers frequently asked questions for CircleCI’s machine runner.

How can I tell whether a host with a self-hosted runner installed is executing a job?

The recommended approach at this time is to query the host with the following command:

ps aux | pgrep -f circleci-launch-agent

If the result of the command above returns greater than two processes, you can assume that the machine runner is executing a task.

Note that you must check to see if there are greater than two processes because the grep process itself will count as one process and the launch-agent process will count as a separate process.


Is it possible to split the .circleci/config.yml into different files?

Splitting your .circleci/config.yml into multiple files is not supported. If you would like more information on this, you can view this support article.

While splitting configuration files is not supported, CircleCI does support dynamic configurations, which allows you to create configuration files based on specific pipeline values or paths. See the Dynamic configuration page for more information.

Can I trigger forked PRs using pipelines?

You can trigger pipelines to build PRs from forked repositories with CircleCI API v2. However, by default, CircleCI will not build a PR from a forked repository. If you would like to turn this feature on, navigate to Project Settings  Advanced in the web app. If you would like more information, you can view this support article.

Scheduled pipelines

Can I migrate existing scheduled workflows to scheduled pipelines?

Yes, visit the Scheduled pipelines migration guide for more information.

How do I find the schedules that I have created?

As scheduled pipelines are stored directly in CircleCI, there is a UUID associated with each schedule. You can view schedules that you have created on the Triggers page of the project settings. You can also list all the schedules under a single project:

curl --location --request GET "<project-slug>/schedule" \
--header "circle-token: <PERSONAL_API_KEY>"

Refer to the Getting started with the API section of the API Developer’s Guide for more guidance on making requests.

What time zone is used for scheduled pipelines?

Coordinated Universal Time (UTC) is the time zone in which schedules are interpreted.

Can pipelines be scheduled to run at a specific time of day?

Yes, you can Scheduled pipelines. You can set up scheduled pipelines through the CircleCI web app, or with CircleCI API v2.

If you are currently using Scheduled workflows, please see the Migration guide to update your scheduled workflows to scheduled pipelines.

Are scheduled pipelines guaranteed to run at precisely the time scheduled?

CircleCI provides no guarantees about precision. A schedule will be run as if the commit was pushed at the configured time.

Why did my scheduled pipeline run later than expected?

There is a nuanced difference in the scheduling expression with Scheduled Pipelines, compared to the Cron expression.

For example, when you express the schedule as 1 per-hour for 08:00 UTC, the scheduled pipeline will run once within the 08:00 to 09:00 UTC window. Note that it does not mean that it will run at 08:00 UTC exactly.

However, subsequent runs of the scheduled pipeline will always be run on the same time as its previous run. In other words, if a previous scheduled pipeline ran at 08:11 UTC, the next runs should also be at 08:11 UTC.

Do you support regex?

Not currently. Scheduled pipelines require highly deterministic inputs such as a commit SHA, branch, or tag (fully qualified, no regexes) included in the webhook, API call, or schedule.


How many jobs can I run concurrently?

The number of jobs you can run concurrently differs between plans. When using workflows to schedule jobs, you can use a fan-out/fan-in method to run jobs concurrently.

Can I use multiple executor types in the same workflow?

Yes, this is supported. See the Sample configuration page for examples.

Can I build only the jobs that changed?

You can set up your workflows to conditionally run jobs based on specific updates to your repository. You can do this with Conditional workflows and Dynamic configurations. Dynamic configurations will dynamically generate CircleCI configuration and pipeline parameters, and run the resulting work within the same pipeline.

Dynamic configuration

I thought pipeline parameters could only be used with the API?

Previously, this was true. With the dynamic configuration feature, you can now set pipeline parameters dynamically, before the pipeline is executed (triggered from either the API or a webhook—a push event to your VCS).

Can I use a custom executor?

Custom executors can be used, but require certain dependencies to be installed for the continuation step to work (currently: curl, jq).

What is the continuation orb?

The continuation orb assists you in managing the pipeline continuation process. The continuation orb wraps an API call to continuePipeline. Refer to the continuation orb documentation for more information.

Is it possible to not use the continuation orb?

If you have special requirements not covered by the continuation orb, you can implement the same functionality in other ways. Refer to the orb source code to learn how the continuation functionality is implemented with the orb.


Visit our Pricing page to find details about CircleCI’s plans.

What are credits?

Credits are used to pay for users and usage based on machine type, size, and features such as Docker Layer Caching.

For example, the 25,000 credit package would provide 2,500 build minutes when using a Docker or Linux "medium" compute at 10 credits per minute. CircleCI provides multiple compute sizes so you can optimize builds between performance (improved developer productivity) and value.

When applicable, build time can be further reduced by using parallelism, which splits the job into multiple tests that are executed at the same time. With 2x parallelism, a build that usually runs for 2,500 minutes could be executed in 1,250 minutes, further improving developer productivity. Note that when two executors are running in parallel for 1,250 minutes each, total build time remains 2,500 minutes.

How do I buy credits? Can I buy in any increments?

Every month, you are charged for your selected credit package at the beginning of the month.

What do I pay for?

You can choose to pay for premium features per active user, compute, and optionally, premium support.

  • Access to features, such as new machine sizes, are paid with a monthly fee of 25,000 credits per active user (not including applicable taxes).

  • Compute is paid for monthly in credits for the machine size and duration you use:

    • Credits are sold in packages of 25,000 at $15 each (not including applicable taxes).

    • Credits rollover each month and expire after one year.

  • Docker Layer Caching (DLC) is paid for with credits per usage, similar to compute credits.

What happens when I run out of credits?

On the Performance plan, when you reach 0 credits, you will be refilled 25% of your credit subscription, with a minimum refill of 25,000 credits. For example, if your monthly package size is 100,000 credits, you will automatically be refilled 25,000 credits (at $.0006 each, not including applicable taxes) when you reach 2000 remaining credits.

If you notice that your account is receiving repeated refills, review your credit usage by logging in to the CircleCI web app > click Plan > click Plan Usage. In most cases, increasing your credit package should minimize repeat refills. You can manage your plan by clicking Plan Overview.

On the Free plan, jobs will fail to run once you have run out of credits.

Do credits expire?

Performance plan: Credits expire one year after purchase. Unused credits will be forfeited when the account subscription is canceled.

How do I pay?

You can pay from inside the CircleCI app for monthly pricing.

When do I pay?

On the Performance plan, at the beginning of your billing cycle, you will be charged for premium support tiers and your monthly credit allocation. Any subsequent credit refills during the month (such as the auto-refilling at 25% when there are 0 credits remaining) will be paid at the time of the refill.

What is prepaid billing?

Prepaid billing is a payment option for customers on the Performance plan. Prepaid Billing allows you to purchase credits in bulk, pay upfront, and be able to get discounted prices for credits based on volume purchased.

How can I get on prepaid billing?

All Performance plan customers can choose to get on prepaid billing through the CircleCI web app. To access this option, follow these steps:

  1. Select Plan in the web app

  2. Select the Manage tab

  3. Select to Set up and switch to get started switching to prepaid billing

I still have credits from my Monthly subscription, what happens if I get on prepaid billing now?

You will still have access to any balance credits that were previously purchased, and the 12 month expiry date will remain.

I selected prepaid billing but I didn’t receive a discount. Why?

Discounting for prepaid billing starts at a purchase volume of 5 Million credits onwards.

What happens when I run out of all my prepaid billing credits?

Similar to what happens today on Performance plans, when you run out of credits your credit package will be automatically renewed at the purchase level you have selected.

When will I be charged for my prepaid billing purchase?

Upon selecting prepaid billing, your credit card will be charged immediately. Subsequently, when you run out of credits, your credit card will be charged again to provide you with a refill.

I want to change my upcoming prepaid billing refill, how do I do that?

You can follow these steps:

  1. Select *Plan in the web app

  2. Select the Manage tab

  3. Click the pencil icon in the Credits section to edit your auto refill rate

Do I still get 30,000 bonus credits and 5 free seats on prepaid billing?

Yes, all prepaid billing customers still receive the benefit of 30,000 credits and 5 free user seats every month.

Is there a way to share plans across organizations and have them billed centrally?

Yes, log in to the CircleCI web app > select Plan in the sidebar > click Share & Transfer.

On non-free plans, you can share your plan with free organizations for which you have admin access using the Add Shared Organization option. All orgs you have shared your plan with will then be listed on the Share & Transfer page and child organizations will bill all credits and other usage to the parent org.

On non-free plans, you can transfer your plan to another free organization for which you have admin access using the Transfer Plan option. When you transfer a paid plan to another org, your org will be downgraded to the free plan.

If a container is used for under one minute, do I have to pay for a full minute?

You pay to the next nearest credit. First we round up to the nearest second, and then up to the nearest credit.

How do I calculate my monthly storage and network costs?

Calculate your monthly storage and network costs by finding your storage and network usage on the CircleCI web app by navigating to Plan  Plan Usage.


To calculate monthly storage costs from your daily usage, click on the Storage tab to see if your organization has accrued any overages beyond the GB-monthly allotment. Your overage (GB-Months/TB-Months) can be multiplied by 420 credits to estimate the total monthly costs. Example: 2 GB-Months overage x 420 credits = 840 credits ($.50).


Billing for network usage is only applicable to traffic from CircleCI to self-hosted runners. Read more on the Persisting data page.

Your network overage GB/TB can be multiplied by 420 credits to estimate the total monthly costs. Example: 2 GB-Months overage x 420 credits = 840 credits ($.50).

How do I calculate my monthly IP ranges cost?

Calculate your monthly IP ranges costs by finding your IP ranges usage on the CircleCI app by navigating to Plan > Plan Usage.

In addition to the IP Ranges Usage summary, you can navigate to the IP Ranges tab to find more details about your data usage. In this tab, the IP ranges usage value represents the raw number of bytes in or out of the Docker container during execution of a job with IP ranges enabled.

This number includes the job’s overall network transfer and any other bytes that go in or out of the Docker container. Data used to pull in the Docker image to the container before the job starts executing will not incur usage costs for jobs with IP ranges enabled.

This feature will consume 450 credits from your account for each GB of data used for jobs with IP ranges enabled. You can also view job-specific details of IP ranges usage in the Resources tab on the Job Details UI page. See IP ranges pricing for more information.

How do I predict my monthly IP ranges cost without enabling the feature first?

You can view an approximation of network transfer for any Docker job (excluding Remote Docker) in the Resources tab on the Job Details UI page. Convert this value to GB if it is not already in GB and multiply by 450 credits to predict the approximate cost of enabling IP ranges on that Docker job.

Why does CircleCI have per-active-user pricing?

Credit usage covers access to compute. We prefer to keep usage costs as low as possible to encourage frequent job runs, which is the foundation of a good CI practice. Per-active-user fees cover access to platform features and job orchestration. This includes features like dependency caching, artifact caching, and workspaces, all of which speed up build times without incurring additional compute cost.

What constitutes an Active User?

An active user is any user who triggers the use of compute resources on non-OSS projects. This includes activities such as:

  • Commits from users that trigger builds, including PR Merge commits

  • Re-running jobs in the CircleCI web application, including SSH debug

  • Approving manual jobs (approver will be considered the actor of all downstream jobs).

  • Using scheduled workflows

  • Machine users

To find a list of your Active Users, log in to the CircleCI web app, click Plan  Plan Usage  Users.

Am I charged if my job is "Queued" or "Preparing"?

No. If you are notified that a job is "queued", it indicates that your job is waiting due to a plan or concurrency limit. If your job indicates that it is "preparing", it means that CircleCI is setting up or dispatching your job so that it may run.

What are the other renewal dates?

The first credit card charge on the day you upgrade to a paid plan or change paid plans, in addition to the following charges from CircleCI:

  • On the monthly renewal date if your team is on the monthly plan.

  • On the annual renewal date if your team is on the annual plan.

  • On the last day of the month if your team is on the annual plan and there is an outstanding balance from adding new users or utilizing more credits.

  • If you are on the Performance plan, anytime your team’s credit balance drops below your preset limit, another credit purchase will be processed.

Are there credit plans for open source projects?

Open source organizations on our Free plan receive 400,000 free credits per month that can be spent on Linux open source projects. Open-source credit availability and limits will not be visible in the UI.

If you build on macOS, we also offer organizations on our Free plan 25,000 free credits per month to use on macOS open source builds. To find out more, visit the CircleCI support portal, which includes an Ask AI option to get you the information you need. Free credits for macOS open source builds can be used on a maximum of 2 concurrent jobs per organization.

Can I get discounts for open source on the Performance plan?

CircleCI no longer offers discounts for open source customers on the Performance plan.

Why does CircleCI charge for Docker layer caching?

Docker layer caching (DLC) reduces build times on pipelines where Docker images are built by only rebuilding Docker layers that have changed (read more on the Docker Layer Caching page). DLC costs 200 credits per job run.

To estimate your DLC cost, look at the jobs in your config file with Docker layer caching enabled, and the number of Docker images you are building in those jobs. There are cases where a job can be written once in a config file but the job runs multiple times in a pipeline, for example, with parallelism enabled.

Note that the benefits of Docker layer caching are only apparent on pipelines that are building Docker images, and reduces image build times by reusing the unchanged layers of the application image built during your job. If your pipeline does not include a job where Docker images are built, Docker layer caching will provide no benefit.

Cancel Performance Plan

How do I cancel a Performance plan subscription?

You must have admin access in your CircleCI organization to cancel your Performance plan subscription.

  1. In the CircleCI web app, click Plan on the left sidebar and then open the Billing tab.

  2. At the bottom of the page, click "Looking to cancel your plan?"

  3. Click Cancel. Follow the prompts to complete the cancellation.

How do I know if I am an org admin in CircleCI?

For GitHub users, your account has the "Owner" role in your GitHub organization.

For Bitbucket users, your account has "Admin" permissions in your Bitbucket repository.

For GitLab users, your account is listed as "Org Admin" in the CircleCI web app under Organization Settings > People.

What happens upon cancelling a Performance plan subscription?

You will continue to have access to the Performance plan settings in the CircleCI web app and be able to use credits until the end of your current billing cycle. After the cycle ends, your org will be transitioned to the Free plan, where you can use up to 30,000 credits per month.

Note that you will no longer have access to the billing statements after the end of the current billing cycle. Make sure to download your billing statements before then.

What happens to unused credits if a plan is cancelled?

Credits that are unused at the end of the billing cycle will be forfeited and are not eligible for refunds.

Is it possible to reactivate the Performance plan after cancelling the subscription?

Yes, you can always upgrade to the Performance plan from the Plan > Overview page in the CircleCI web app.

Suggest an edit to this page

Make a contribution
Learn how to contribute