Configuration reference
Helpful Resources
On This Page
- version
- setup
- orbs
- commands
- parameters
- executors
- jobs
- <job_name>
- type
- environment
- parallelism
- parameters
- Executor docker / machine / macos
- docker
- Docker registry authentication
- AWS authentication
- Use OIDC
- Use environment variables
- machine
- Available Linux machine images
- Available Linux machine images on server
- Available Linux GPU machine images
- Available Android machine images
- Available Windows machine images
- Available Windows machine images on server
- Available Windows GPU machine image
- macos
- branches - DEPRECATED
- resource_class
- Self-hosted runner
- Docker execution environment
- x86
- Arm
- LinuxVM execution environment
- macOS execution environment
- macOS execution environment on server
- Windows execution environment
- GPU execution environment (Linux)
- GPU execution-environment (Windows)
- Arm VM execution-environment
- steps
- run
- Default shell options
- Background commands
- Shorthand syntax
- The when attribute
- Ending a job from within a step
- The when step
- checkout
- setup_remote_docker
- save_cache
- restore_cache
- deploy - DEPRECATED
- store_artifacts
- store_test_results
- persist_to_workspace
- attach_workspace
- add_ssh_keys
- Using pipeline values
- circleci_ip_ranges
- workflows
- version
- <workflow_name>
- triggers
- schedule
- cron
- filters
- branches
- Using when in workflows
- jobs
- <job_name>
- requires
- name
- context
- type
- filters
- Expression-based job filters
- branches
- tags
- matrix
- Excluding sets of parameters from a matrix
- Dependencies and matrix jobs
- pre-steps and post-steps
- Logic statements
- Logic statement examples
- Example full configuration
This document is a reference for the CircleCI 2.x configuration keys that are used in the .circleci/config.yml
file.
You can see a complete config.yml
in our full example.
version
Key | Required | Type | Description |
---|---|---|---|
| Y | String |
|
The version
field is intended to be used in order to issue warnings for deprecation or breaking changes.
setup
Key | Required | Type | Description |
---|---|---|---|
| N | Boolean | Designates the |
The setup
field enables you to conditionally trigger configurations from outside the primary .circleci
parent directory, update pipeline parameters, or generate customized configurations.
orbs
The orbs key is supported in version: 2.1 configuration |
Key | Required | Type | Description |
---|---|---|---|
| N | Map | A map of user-selected names to either: orb references (strings) or orb definitions (maps). Orb definitions must be the orb-relevant subset of 2.1 config. See the Creating Orbs documentation for details. |
| N | Map | A map of strings to executor definitions. See the |
| N | Map | A map of command names to command definitions. See the |
The following example uses the node
orb that exists in the certified circleci
namespace. Refer to the Node orb page in the Orb Registry for more examples and information.
version: 2.1
orbs:
node: circleci/node@x.y
jobs:
install-node-example:
docker:
- image: cimg/base:stable
steps:
- checkout
- node/install:
install-yarn: true
node-version: '16.13'
- run: node --version
workflows:
test_my_app:
jobs:
- install-node-example
Documentation is available for orbs in the following sections:
Public orbs are listed in the Orb Registry.
commands
The commands key is supported in version: 2.1 configuration |
A command defines a sequence of steps as a map to be executed in a job, enabling you to reuse a single command definition across multiple jobs. For more information see the Reusable Config Reference Guide.
Key | Required | Type | Description |
---|---|---|---|
| Y | Sequence | A sequence of steps run inside the calling job of the command. |
| N | Map | A map of parameter keys. See the Parameter Syntax section of the Reusing Config document for details. |
| N | String | A string that describes the purpose of the command. |
Example:
commands:
sayhello:
description: "A very simple command for demonstration purposes"
parameters:
to:
type: string
default: "Hello World"
steps:
- run: echo << parameters.to >>
parameters
The pipeline parameters key is supported in version: 2.1 configuration |
Pipeline parameters declared for use in the configuration. See Pipeline Values and Parameters for usage details.
Key | Required | Type | Description |
---|---|---|---|
| N | Map | A map of parameter keys. Supports |
executors
The executors key is supported in version: 2.1 configuration |
Executors define the execution environment in which the steps of a job will be run, allowing you to reuse a single executor definition across multiple jobs.
Key | Required | Type | Description |
---|---|---|---|
| Y (1) | List | Options for Docker executor |
| N | String | Amount of CPU and RAM allocated to each container in a job. |
| Y (1) | Map | Options for machine executor |
| Y (1) | Map | Options for macOS executor |
| Y (1) | Map | Windows executor currently working with orbs. Check out the orb. |
| N | String | Shell to use for execution command in all steps. Can be overridden by |
| N | String | In which directory to run the steps. Will be interpreted as an absolute path. |
| N | Map | A map of environment variable names and values. |
(1) One executor type should be specified per job. If more than one is set you will receive an error.
Example:
version: 2.1
executors:
my-executor:
docker:
- image: cimg/ruby:3.0.3-browsers
jobs:
my-job:
executor: my-executor
steps:
- run: echo "Hello executor!"
See the Using Parameters in Executors section of the Reusing config page for examples of parameterized executors.
jobs
A Workflow is comprised of one or more uniquely named jobs. Jobs are specified in the jobs
map, see Sample config.yml for two examples of a job
map. The name of the job is the key in the map, and the value is a map describing the job.
Jobs have a maximum runtime of 1 (Free), 3 (Performance), or 5 (Scale) hours depending on pricing plan. If your jobs are timing out, consider a larger resource_class
and/or parallelism. Additionally, you can upgrade your pricing plan or run some of your jobs concurrently using workflows.
<job_name
>
Each job consists of the job’s name as a key and a map as a value. A name should be case insensitive unique within a current jobs
list. The value map has the following attributes:
Key | Required | Type | Description |
---|---|---|---|
| N | String | Job type, can be |
| Y (1) | List | Options for the Docker executor |
| Y (1) | Map | Options for the machine executor |
| Y (1) | Map | Options for the macOS executor |
| N | String | Shell to use for execution command in all steps. Can be overridden by |
| N | Map | Parameters for making a |
| Y | List | A list of steps to be performed |
| N | String | In which directory to run the steps. Will be interpreted as an absolute path. Default: |
| N | Integer | Number of parallel instances of this job to run (default: 1) |
| N | Map | A map of environment variable names and values. |
| N | Map | This key is deprecated. Use workflows filtering to control which jobs run for which branches. |
| N | String | Amount of CPU and RAM allocated to each container in a job. |
(1) One executor type should be specified per job. If more than one is set you will receive an error.
type
Configure a job type. Options are release
, approval
, build
(default). If a type is not specified, the job defaults to a build
type.
Jobs with the release
type are used to connect your pipeline configuration to a release in the CircleCI releases UI. For full details, see the Releases overview page.
The approval
type is used to configure a manual approval step. No job
configuration is required or allowed for an approval
type job. The approval
type is most commonly configured within a workflow rather than under the top-level jobs
key. Only approval
type jobs can have their type
configured under workflows
. See type under workflows section for full details.
environment
A map of environment variable names and values. For more information on defining and using environment variables, and the order of precedence governing the various ways they can be set, see the Environment variables page.
parallelism
This feature is used to optimize test steps. If parallelism
is set to N > 1, then N independent executors will be set up and each will run the steps of that job in parallel.
You can use the CircleCI CLI to split your test suite across parallel containers so the job completes in a shorter time.
-
Read more about splitting tests across parallel execution environments on the Parallelism and test splitting page.
-
Refer to the Use the CircleCI CLI to split tests how-to guide.
-
Follow the Test splitting tutorial.
Example:
jobs:
build:
docker:
- image: cimg/base:2022.09
environment:
FOO: bar
parallelism: 3
resource_class: large
working_directory: ~/my-app
steps:
- run: go list ./... | circleci tests run --command "xargs gotestsum --junitfile junit.xml --format testname --" --split-by=timings --timings-type=name
parameters
Job-level parameters
can be used when calling a job
in a workflow
.
Reserved parameter-names:
-
name
-
requires
-
context
-
type
-
filters
-
matrix
See Parameter Syntax for definition details.
Executor docker
/ machine
/ macos
CircleCI offers several execution environments in which to run your jobs. To specify an execution environment choose an executor, then specify and image and a resource class. An executor defines the underlying technology, environment, and operating system in which to run a job.
Set up your jobs to run using the docker
(Linux), machine
(LinuxVM, Windows, GPU, Arm), or macos
executor, then specify an image with the tools and packages you need, and a resource class.
Learn more about execution environments and executors in the Introduction to Execution Environments.
docker
Configured by docker
key which takes a list of maps:
Key | Required | Type | Description |
---|---|---|---|
| Y | String | The name of a custom Docker image to use. The first |
| N | String |
|
| N | String or List | The command used as executable when launching the container. |
| N | String or List | The command used as PID 1 (or arguments for entrypoint) when launching the container. |
| N | String | Which user to run commands as within the Docker container |
| N | Map | A map of environment variable names and values. The |
| N | Map | Authentication for registries using standard |
| N | Map | Authentication for AWS Elastic Container Registry (ECR) |
For a primary container, (the first container in the list) if neither command
nor entrypoint
is specified in the configuration, then any ENTRYPOINT
and COMMAND
in the image are ignored. This is because the primary container is typically only used for running the steps
and not for its ENTRYPOINT
, and an ENTRYPOINT
may consume significant resources or exit prematurely. A custom image may disable this behavior and force the ENTRYPOINT
to run.
You can specify image versions using tags or digest. You can use any public images from any public Docker registry (defaults to Docker Hub). Learn more about specifying images on the Using the Docker Execution Environment page.
Docker registry authentication
Some registries, Docker Hub, for example, may rate limit anonymous Docker pulls. We recommend that you authenticate to pull private and public images. The username and password can be specified in the auth
field. See Using Docker Authenticated Pulls for details.
Example:
jobs:
build:
docker:
- image: buildpack-deps:trusty # primary container
auth:
username: mydockerhub-user
password: $DOCKERHUB_PASSWORD # context / project UI env-var reference
environment:
ENV: CI
- image: mongo:2.6.8
auth:
username: mydockerhub-user
password: $DOCKERHUB_PASSWORD # context / project UI env-var reference
command: [--smallfiles]
- image: postgres:14.2
auth:
username: mydockerhub-user
password: $DOCKERHUB_PASSWORD # context / project UI env-var reference
environment:
POSTGRES_USER: user
- image: redis@sha256:54057dd7e125ca41afe526a877e8bd35ec2cdd33b9217e022ed37bdcf7d09673
auth:
username: mydockerhub-user
password: $DOCKERHUB_PASSWORD # context / project UI env-var reference
- image: acme-private/private-image:321
auth:
username: mydockerhub-user
password: $DOCKERHUB_PASSWORD # context / project UI env-var reference
AWS authentication
Using an image hosted on AWS ECR requires authentication using AWS credentials.
Use OIDC
Authenticate using OpenID Connect (OIDC) using the oidc_role_arn
field, as follows:
jobs:
job_name:
docker:
- image: <your-image-arn>
aws_auth:
oidc_role_arn: <your-iam-role-arn>
For steps to get set up with OIDC to pull images from AWS ECR, see the Pull and image from AWS ECR with OIDC page.
Use environment variables
By default, CircleCI uses the AWS credentials you provide by setting the AWS_ACCESS_KEY_ID
and AWS_SECRET_ACCESS_KEY
project environment variables. It is also possible to set the credentials by using the aws_auth
field as in the following example:
jobs:
build:
docker:
- image: account-id.dkr.ecr.us-east-1.amazonaws.com/org/repo:0.1
aws_auth:
aws_access_key_id: AKIAQWERVA # can specify string literal values
aws_secret_access_key: $ECR_AWS_SECRET_ACCESS_KEY # or project UI envar reference
machine
CircleCI cloud The use of machine: true is deprecated. You must specify an image to use. |
The machine executor is configured using the machine
key, which takes a map:
Key | Required | Type | Description |
---|---|---|---|
| Y | String | The virtual machine image to use. View available images. Note: This key is not supported for Linux VMs on installations of CircleCI server. For information about customizing |
| N | Boolean | Set this to |
Example:
jobs:
build: # name of your job
machine: # executor type
image: ubuntu-2004:current # recommended linux image - includes Ubuntu 20.04, docker 19.03.13, docker-compose 1.27.4
steps:
# Commands run in a Linux virtual machine environment
Available Linux machine
images
Specifying an image in your configuration file is strongly recommended. CircleCI supports multiple Linux machine images that can be specified in the image
field. For a full list of supported image tags, refer to the following pages in the Developer Hub:
More information on the software available in each image can be found in our Discuss forum.
The machine executor supports Docker Layer Caching, which is useful when you are building Docker images during your job or Workflow.
Available Linux machine
images on server
If you are using CircleCI server, contact your system administrator for details of available Linux machine images.
Available Linux GPU machine
images
When using the Linux GPU executor, the available images are:
-
linux-cuda-11:default
v11.4, v11.6, v11.8 (default), Docker v20.10.24 -
linux-cuda-12:default
v12.0, v12.1 (default), Docker v20.10.24
Available Android machine
images
CircleCI supports running jobs on Android for testing and deploying Android applications.
To use the Android image directly with the machine executor, add the following to your job:
version: 2.1
jobs:
build:
machine:
image: android:2022.09.1
The Android image can also be accessed using the Android orb.
For examples, refer to the Using Android Images with the Machine Executor page.
Available Windows machine
images
Specifying an image in your configuration file is strongly recommended. CircleCI supports multiple Windows machine images that can be specified in the image
field.
For a full list of supported images, refer to one of the following:
More information on what software is available in each image can be found in our Discuss forum.
Alternatively, use the Windows orb to manage your Windows execution environment. For examples, see the Using the Windows Execution Environment page.
Available Windows machine
images on server
If you are using CircleCI server, contact your system administrator for details of available Windows machine images.
Available Windows GPU machine
image
When using the Windows GPU executor, the available image is:
Example
version: 2.1
jobs:
build:
machine:
image: windows-server-2019-cuda:current
macos
CircleCI supports running jobs on macOS, to allow you to build, test, and deploy apps for macOS, iOS, tvOS and watchOS. To run a job in a macOS virtual machine, add the macos
key to the top-level configuration for your job and specify the version of Xcode you would like to use.
Key | Required | Type | Description |
---|---|---|---|
| Y | String | The version of Xcode that is installed on the virtual machine, see the Supported Xcode Versions section of the Testing iOS document for the complete list. |
Example: Use a macOS virtual machine with Xcode version 14.2.0:
jobs:
build:
macos:
xcode: "14.2.0"
branches
- DEPRECATED
This key is deprecated. Use workflows filtering to control which jobs run for which branches.
resource_class
The resource_class
feature allows you to configure CPU and RAM resources for each job. Resource classes are available for each execution environment, as described in the tables below.
We implement soft concurrency limits for each resource class to ensure our system remains stable for all customers. If you are on a Performance or Custom Plan and experience queuing for certain resource classes, it is possible you are hitting these limits. Contact CircleCI support to request a raise on these limits for your account.
If you do not specify a resource class, CircleCI will use a default value that is subject to change. It is best practice to specify a resource class as opposed to relying on a default.
Java, Erlang and any other languages that introspect the /proc directory for information about CPU count may require additional configuration to prevent them from slowing down when using the CircleCI resource class feature. Programs with this issue may request 32 CPU cores and run slower than they would when requesting one core. Users of languages with this issue should pin their CPU count to their guaranteed CPU resources. |
If you want to confirm how much memory you have been allocated, you can check the cgroup memory hierarchy limit with grep hierarchical_memory_limit /sys/fs/cgroup/memory/memory.stat . |
Self-hosted runner
Use the resource_class
key to configure a self-hosted runner instance.
For example:
jobs:
job_name:
machine: true
resource_class: <my-namespace>/<my-runner>
Docker execution environment
Example:
jobs:
build:
docker:
- image: cimg/base:2022.09
resource_class: xlarge
steps:
... // other config
x86
For credit and access information, see the Resource classes page. Resource class access is dependent on your Plan. |
Class | vCPUs | RAM | Cloud | Server |
---|---|---|---|---|
| 1 | 2GB | ||
| 2 | 4GB | ||
| 3 | 6GB | ||
| 4 | 8GB | ||
| 8 | 16GB | ||
| 16 | 32GB | ||
| 20 | 40GB |
Arm
Arm on Docker For pricing information, and a list of CircleCI Docker convenience images that support Arm resource classes, see the Resource classes page.
Arm on Docker For credit and access information see the Resource classes page. Resource class access is dependent on your Plan To find out which CircleCI Docker convenience images support Arm resource classes, you can refer to Docker hub:
|
Class | vCPUs | RAM | Cloud | Server |
---|---|---|---|---|
| 2 | 8 GB | ||
| 4 | 16 GB | ||
| 8 | 32 GB | ||
| 16 | 64 GB |
LinuxVM execution environment
Class | vCPUs | RAM | Disk Size | Cloud | Server |
---|---|---|---|---|---|
| 2 | 7.5 GB | 150GB | ||
| 4 | 15 GB | 150GB | ||
| 8 | 32 GB | 150GB | ||
| 16 | 64 GB | 150GB | ||
| 32 | 64 GB | 150GB |
Example:
jobs:
build:
machine:
image: ubuntu-2004:202010-01 # recommended linux image
resource_class: large
steps:
... // other config
macOS execution environment
Class | vCPUs | RAM | Cloud | Server |
---|---|---|---|---|
| 4 @ 3.2 GHz | 6GB | ||
| 8 @ 3.2 GHz | 12GB | ||
| 4 @ 3.49 GHz | 8GB | ||
| 8 @ 3.49 GHz | 16GB |
We have deprecated support for all Intel-based macOS resources. The See our announcement for more details. |
Example
jobs:
build:
macos:
xcode: "15.4.0"
resource_class: m2pro.medium
steps:
... // other config
macOS execution environment on server
If you are working on CircleCI server v3.1 and up, you can access the macOS execution environment using self-hosted runner.
Windows execution environment
Class | vCPUs | RAM | Disk Size | Cloud | Server |
---|---|---|---|---|---|
| 4 | 15GB | 200 GB | ||
| 8 | 30GB | 200 GB | ||
| 16 | 60GB | 200 GB | ||
| 32 | 128GB | 200 GB |
Using server? Check with your systems administrator whether you have access to the Windows execution environment. |
Example:
version: 2.1
jobs:
build: # name of your job
resource_class: 'windows.medium'
machine:
image: 'windows-server-2022-gui:current'
shell: 'powershell.exe -ExecutionPolicy Bypass'
steps:
# Commands are run in a Windows virtual machine environment
- checkout
- run: Write-Host 'Hello, Windows'
GPU execution environment (Linux)
Class | vCPUs | RAM | GPUs | GPU model | GPU Memory (GiB) | Disk Size (GiB) | Cloud | Server |
---|---|---|---|---|---|---|---|---|
| 4 | 16 | 1 | NVIDIA Tesla P4 | 16 | 150 | ||
| 4 | 16 | 1 | NVIDIA A10G | 24 | 150 | ||
| 4 | 15 | 2 | NVIDIA Tesla T4 | 16 | 150 | ||
| 8 | 30 | 4 | NVIDIA Tesla T4 | 16 | 150 | ||
| 8 | 30 | 1 | NVIDIA Tesla T4 | 16 | 150 | ||
| 8 | 30 | 1 | NVIDIA Tesla V100 | 16 | 150 |
Example:
version: 2.1
jobs:
build:
machine:
image: linux-cuda-12:default
resource_class: gpu.nvidia.medium
steps:
- run: nvidia-smi
- run: docker run --gpus all nvidia/cuda:9.0-base nvidia-smi
See the Available Linux GPU images section for the full list of available images.
GPU execution-environment (Windows)
Class | vCPUs | RAM | GPUs | GPU model | GPU Memory (GiB) | Disk Size (GiB) | Cloud | Server |
---|---|---|---|---|---|---|---|---|
| 16 | 60 | 1 | NVIDIA Tesla T4 | 16 | 200 |
Example:
version: 2.1
orbs:
win: circleci/windows@5.0.0
jobs:
build:
executor: win/server-2019-cuda
steps:
- checkout
- run: '&"C:\Program Files\NVIDIA Corporation\NVSMI\nvidia-smi.exe"'
(2) This resource requires review by our support team. Open a support ticket if you would like to request access.
Arm VM execution-environment
Class | vCPUs | RAM | Disk Size | Cloud | Server |
---|---|---|---|---|---|
| 2 | 8GB | 100 GB | ||
| 4 | 16GB | 100 GB | ||
| 8 | 32GB | 100 GB | ||
| 16 | 64GB | 100 GB |
Using server? Check with your systems administrator whether you have access to the Arm execution environment. |
Example:
jobs:
my-job:
machine:
image: ubuntu-2004:202101-01
resource_class: arm.medium
steps:
- run: uname -a
- run: echo "Hello, Arm!"
steps
The steps
setting in a job should be a list of single key/value pairs, the key of which indicates the step type. The value may be either a configuration map or a string (depending on what that type of step requires). For example, using a map:
jobs:
build:
working_directory: ~/canary-python
environment:
FOO: bar
steps:
- run:
name: Running tests
command: make test
Here run
is a step type. The name
attribute is used by the UI for display purposes. The command
attribute is specific for run
step and defines command to execute.
Some steps may implement a shorthand semantic. For example, run
may be also be called like this:
jobs:
build:
steps:
- run: make test
In its short form, the run
step allows us to directly specify which command
to execute as a string value. In this case step itself provides default suitable values for other attributes (name
here will have the same value as command
, for example).
Another shorthand, which is possible for some steps, is to use the step name as a string instead of a key/value pair:
jobs:
build:
steps:
- checkout
In this case, the checkout
step will check out project source code into the job’s working_directory
.
In general all steps can be described as:
Key | Required | Type | Description |
---|---|---|---|
| Y | Map or String | A configuration map for the step or some string whose semantics are defined by the step. |
Each built-in step is described in detail below.
run
Used for invoking all command-line programs, taking either a map of configuration values, or, when called in its short-form, a string that will be used as both the command
and name
. Run commands are executed using non-login shells by default, so you must explicitly source any dotfiles as part of the command.
the run step replaces the deprecated deploy step. If your job has a parallelism of 1, the deprecated deploy step can be swapped out directly for the run step. If your job has parallelism > 1 , see Migrate from deploy to run. |
Key | Required | Type | Description |
---|---|---|---|
| Y | String | Command to run via the shell |
| N | String | Title of the step to be shown in the CircleCI UI (default: full |
| N | String | Shell to use for execution command (default: See Default Shell Options) |
| N | Map | Additional environmental variables, locally scoped to command |
| N | Boolean | Whether or not this step should run in the background (default: false) |
| N | String | In which directory to run this step. Will be interpreted relative to the |
| N | String | Elapsed time the command can run without output. The string is a decimal with unit suffix, such as "20m", "1.25h", "5s". The default is 10 minutes and the maximum is governed by the maximum time a job is allowed to run. |
| N | String | Specify when to enable or disable the step. Takes the following values: |
Each run
declaration represents a new shell. It is possible to specify a multi-line command
, each line of which will be run in the same shell:
- run:
command: |
echo Running test
mkdir -p /tmp/test-results
make test
You can also configure commands to run in the background if you do not want to wait for the step to complete before moving on to subsequent run steps.
Default shell options
For jobs that run on Linux, the default value of the shell
option is /bin/bash -eo pipefail
if /bin/bash
is present in the build container. Otherwise it is /bin/sh -eo pipefail
. The default shell is not a login shell (--login
or -l
are not specified). Hence, the shell will not source your ~/.bash_profile
, ~/.bash_login
, ~/.profile
files.
For jobs that run on macOS, the default shell is /bin/bash --login -eo pipefail
. The shell is a non-interactive login shell. The shell will execute /etc/profile/
followed by ~/.bash_profile
before every step.
For more information about which files are executed when Bash is invocated, see the INVOCATION
section of the bash
manpage.
Descriptions of the -eo pipefail
options are provided below.
-e
Exit immediately if a pipeline (which may consist of a single simple command), a subshell command enclosed in parentheses, or one of the commands executed as part of a command list enclosed by braces exits with a non-zero status.
So if in the previous example mkdir
failed to create a directory and returned a non-zero status, then command execution would be terminated, and the whole step would be marked as failed. If you desire the opposite behaviour, you need to add set +e
in your command
or override the default shell
in your configuration map of run
. For example:
- run:
command: |
echo Running test
set +e
mkdir -p /tmp/test-results
make test
- run:
shell: /bin/sh
command: |
echo Running test
mkdir -p /tmp/test-results
make test
-o pipefail
If pipefail is enabled, the pipeline’s return status is the value of the last (rightmost) command to exit with a non-zero status, or zero if all commands exit successfully. The shell waits for all commands in the pipeline to terminate before returning a value.
For example:
- run: make test | tee test-output.log
If make test
fails, the -o pipefail
option will cause the whole step to fail. Without -o pipefail
, the step will always run successfully because the result of the whole pipeline is determined by the last command (tee test-output.log
), which will always return a zero status.
If make test fails the rest of pipeline will be executed. |
If you want to avoid this behaviour, you can specify set +o pipefail
in the command or override the whole shell
(see example above).
In general, we recommend using the default options (-eo pipefail
) because they show errors in intermediate commands and simplify debugging job failures. For convenience, the UI displays the used shell and all active options for each run
step.
For more information, see the Using Shell Scripts document.
Background commands
The background
attribute enables you to configure commands to run in the background. Job execution will immediately proceed to the next step rather than waiting for return of a command with the background
attribute set to true
. The following example shows the configuration for running the X virtual framebuffer in the background which is commonly required to run Selenium tests:
- run:
name: Running X virtual framebuffer
command: Xvfb :99 -screen 0 1280x1024x24
background: true
- run: make test
Shorthand syntax
run
has a very convenient shorthand syntax:
- run: make test
# shorthanded command can also have multiple lines
- run: |
mkdir -p /tmp/test-results
make test
In this case, command
and name
become the string value of run
, and the rest of the config map for that run
have their default values.
The when
attribute
By default, CircleCI will execute job steps one at a time, in the order that they are defined in config.yml
, until a step fails (returns a non-zero exit code). After a command fails, no further job steps will be executed.
Adding the when
attribute to a job step allows you to override this default behaviour, and selectively run or skip steps depending on the status of the job.
The default value of on_success
means that the step will run only if all of the previous steps have been successful (returned exit code 0).
A value of always
means that the step will run regardless of the exit status of previous steps. This is useful if you have a task that you want to run regardless of whether the previous steps are successful or not. For example, you might have a job step that needs to upload logs or code-coverage data somewhere.
A value of on_fail
means that the step will run only if one of the preceding steps has failed (returns a non-zero exit code). It is common to use on_fail
if you want to store some diagnostic data to help debug test failures, or to run custom notifications about the failure, such as sending emails or triggering alerts.
Some steps, such as store_artifacts and store_test_results will always run, even if a step has failed (returned a non-zero exit code) previously. The when attribute, store_artifacts and store_test_results are not run if the job has been killed by a cancel request or has reached the runtime timeout limit. |
- run:
name: Upload CodeCov.io Data
command: bash <(curl -s https://codecov.io/bash) -F unittests
when: always # Uploads code coverage results, pass or fail
Ending a job from within a step
A job can exit without failing by using run: circleci-agent step halt
. However, if a step within the job is already failing then the job will continue to fail. This can be useful in situations where jobs need to conditionally execute.
Here is an example where halt
is used to avoid running a job on the develop
branch:
run: |
if [ "$CIRCLE_BRANCH" = "develop" ]; then
circleci-agent step halt
fi
The when
step
The when and unless steps are supported in version: 2.1 configuration |
A conditional step consists of a step with the key when
or unless
. Under the when
key are the subkeys condition
and steps
. The purpose of the when
step is customizing commands and job configuration to run on custom conditions (determined at config-compile time) that are checked before a workflow runs. See the Conditional Steps section of the reusable configuration reference for more details.
Key | Required | Type | Description |
---|---|---|---|
| Y | Logic | |
| Y | Sequence | A list of steps to execute when the condition is true |
Example:
version: 2.1
jobs: # conditional steps may also be defined in `commands:`
job_with_optional_custom_checkout:
parameters:
custom_checkout:
type: string
default: ""
machine:
image: ubuntu-2004:202107-02
steps:
- when:
condition: <<parameters.custom_checkout>>
steps:
- run: echo "my custom checkout"
- unless:
condition: <<parameters.custom_checkout>>
steps:
- checkout
workflows:
build-test-deploy:
jobs:
- job_with_optional_custom_checkout:
custom_checkout: "any non-empty string is truthy"
- job_with_optional_custom_checkout
checkout
Blobless clones To help improve the overall performance of code checkouts from Git source code hosts, a "blobless" strategy is being rolled out. This reduces the amount of data fetched from the remote, by asking the remote to filter out objects that are not attached to the current commit. While this improves performance in most cases, if a downstream step requires those objects to exist for scanning or comparisons, it can cause failures. To work around these potential problems, a fetch directly after a checkout will ensure the required data is available: |
A special step used to check out source code to the configured path
(defaults to the working_directory
). The reason this is a special step is because it is more of a helper function designed to simplify the process of checking out code. If you require doing git over HTTPS you should not use this step as it configures git to checkout over SSH.
Key | Required | Type | Description |
---|---|---|---|
| N | String | Checkout directory. Will be interpreted relative to the |
If path
already exists and is:
-
A git repository - step will not clone whole repository, instead will fetch origin
-
NOT a git repository - step will fail.
In the case of checkout
, the step type is just a string with no additional attributes:
- checkout
The checkout command automatically adds the required authenticity keys for interacting with GitHub and Bitbucket over SSH, which is detailed further in our integration guide — this guide will also be helpful if you wish to implement a custom checkout command.
CircleCI does not check out submodules. If your project requires submodules, add run
steps with appropriate commands as shown in the following example:
- checkout
- run: git submodule sync
- run: git submodule update --init
The checkout step will configure Git to skip automatic garbage collection. If you are caching your .git directory with restore_cache and would like to use garbage collection to reduce its size, you may wish to use a run step with command git gc before doing so. |
setup_remote_docker
Allows Docker commands to be run locally. See Running Docker commands for details.
jobs:
build:
docker:
- image: cimg/base:2022.06
steps:
# ... steps for building/testing app ...
- setup_remote_docker:
version: default
Key | Required | Type | Description |
---|---|---|---|
| N | boolean | Set this to |
| N | String | Version string of Docker you would like to use (default: |
|
save_cache
Generates and stores a cache of a file or directory of files such as dependencies or source code in our object storage. Later jobs can restore this cache. Learn more on the Caching Dependencies page.
Cache retention can be customized on the CircleCI web app by navigating to .
Key | Required | Type | Description |
---|---|---|---|
| Y | List | List of directories which should be added to the cache |
| Y | String | Unique identifier for this cache |
| N | String | Title of the step to be shown in the CircleCI UI (default: "Saving Cache") |
| N | String | Specify when to enable or disable the step. Takes the following values: |
The cache for a specific key
is immutable and cannot be changed once written.
If the cache for the given key already exists it will not be modified, and job execution will proceed to the next step. |
When storing a new cache, the key
value may contain special, templated, values for your convenience:
Template | Description |
---|---|
| The VCS branch currently being built. |
| The CircleCI build number for this build. |
| The VCS revision currently being built. |
| The SSH key used to checkout the repository. |
| The environment variable |
| A base64 encoded SHA256 hash of the given filename’s contents. This should be a file committed in your repository and may also be referenced as a path that is absolute or relative from the current working directory. Good candidates are dependency manifests, such as |
| The current time in seconds since the UNIX epoch. |
| The OS and CPU information. Useful when caching compiled binaries that depend on OS and CPU architecture, for example, |
During step execution, the templates above will be replaced by runtime values and use the resultant string as the key
.
Template examples:
-
myapp-{{ checksum "package-lock.json" }}
- cache will be regenerated every time something is changed inpackage-lock.json
file, different branches of this project will generate the same cache key. -
myapp-{{ .Branch }}-{{ checksum "package-lock.json" }}
- same as the previous one, but each branch will generate separate cache -
myapp-{{ epoch }}
- every run of a job will generate a separate cache
While choosing suitable templates for your cache key
, keep in mind that cache saving is not a free operation, because it will take some time to upload the cache to our storage. Best practice is to have a key
that generates a new cache only if something actually changed and avoid generating a new one every time a job is run.
Given the immutability of caches, it might be helpful to start all your cache keys with a version prefix v1-... . That way you will be able to regenerate all your caches just by incrementing the version in this prefix. |
Example:
- save_cache:
key: v1-myapp-{{ arch }}-{{ checksum "project.clj" }}
paths:
- /home/ubuntu/.m2
- save_cache:
key: v1-{{ checksum "yarn.lock" }}
paths:
- node_modules/workspace-a
- node_modules/workspace-c
|
restore_cache
Restores a previously saved cache based on a key
. Cache needs to have been saved first for this key using the save_cache
step. Learn more in the caching documentation.
Key | Required | Type | Description |
---|---|---|---|
| Y (1) | String | Single cache key to restore |
| Y (1) | List | List of cache keys to lookup for a cache to restore. Only first existing key will be restored. |
| N | String | Title of the step to be shown in the CircleCI UI (default: "Restoring Cache") |
(1) at least one attribute has to be present. If key
and keys
are both given, key
will be checked first, and then keys
.
A key is searched against existing keys as a prefix.
When there are multiple matches, the most recent match will be used, even if there is a more precise match. |
For example:
steps:
- save_cache:
key: v1-myapp-cache
paths:
- ~/d1
- save_cache:
key: v1-myapp-cache-new
paths:
- ~/d2
- run: rm -f ~/d1 ~/d2
- restore_cache:
key: v1-myapp-cache
In this case cache v1-myapp-cache-new
will be restored because it’s the most recent match with v1-myapp-cache
prefix even if the first key (v1-myapp-cache
) has exact match.
For more information on key formatting, see the key
section of save_cache
step.
When CircleCI encounters a list of keys
, the cache will be restored from the first one matching an existing cache. Most probably you would want to have a more specific key to be first (for example, cache for exact version of package-lock.json
file) and more generic keys after (for example, any cache for this project). If no key has a cache that exists, the step will be skipped with a warning.
A path is not required here because the cache will be restored to the location from which it was originally saved.
Example:
- restore_cache:
keys:
- v1-myapp-{{ arch }}-{{ checksum "project.clj" }}
# if cache for exact version of `project.clj` is not present then load any most recent one
- v1-myapp-
# ... Steps building and testing your application ...
# cache will be saved only once for each version of `project.clj`
- save_cache:
key: v1-myapp-{{ arch }}-{{ checksum "project.clj" }}
paths:
- /foo
deploy
- DEPRECATED
See run
for current processes. If you have parallelism > 1
in your job, see the Migrate from deploy to run guide.
store_artifacts
Step to store artifacts (for example logs, binaries, etc) to be available in the web app or through the API. See the Uploading Artifacts page for more information.
Key | Required | Type | Description |
---|---|---|---|
| Y | String | Directory in the primary container to save as job artifacts |
| N | String | Prefix added to the artifact paths in the artifacts API (default: the directory of the file specified in |
There can be multiple store_artifacts
steps in a job. Using a unique prefix for each step prevents them from overwriting files.
Artifact storage retention can be customized on the CircleCI web app by navigating to .
Example:
- run:
name: Build the Jekyll site
command: bundle exec jekyll build --source jekyll --destination jekyll/_site/docs/
- store_artifacts:
path: jekyll/_site/docs/
destination: circleci-docs
store_test_results
Special step used to upload and store test results for a build. Test results are visible on the CircleCI web application under each build’s Test Summary section. Storing test results is useful for timing analysis of your test suites. For more information on storing test results, see the Collecting Test Data page.
It is also possible to store test results as build artifacts. For steps, refer to the store_artifacts
step section.
Key | Required | Type | Description |
---|---|---|---|
| Y | String | Path (absolute, or relative to your |
Example:
Directory structure:
test-results
├── jest
│ └── results.xml
├── mocha
│ └── results.xml
└── rspec
└── results.xml
config.yml
syntax:
- store_test_results:
path: test-results
persist_to_workspace
Special step used to persist a temporary file to be used by another job in the workflow. For more information on using workspaces, see the Using Workspaces to Share Data Between Jobs page.
persist_to_workspace
adopts the storage settings from the storage customization controls on the CircleCI web app. If no custom setting is provided, persist_to_workspace
defaults to 15 days.
Workspace storage retention can be customized on the CircleCI web app by navigating to .
Key | Required | Type | Description |
---|---|---|---|
| Y | String | Either an absolute path or a path relative to |
| Y | List | Glob identifying file(s), or a non-glob path to a directory to add to the shared workspace. Interpreted as relative to the workspace root. Must not be the workspace root itself. |
The root key is a directory on the container which is taken to be the root directory of the workspace. The path values are all relative to the root.
Example for root Key
For example, the following step syntax persists the specified paths from /tmp/dir
into the workspace, relative to the directory /tmp/dir
.
- persist_to_workspace:
root: /tmp/dir
paths:
- foo/bar
- baz
After this step completes, the following directories are added to the workspace:
/tmp/dir/foo/bar /tmp/dir/baz
Example for paths Key
- persist_to_workspace:
root: /tmp/workspace
paths:
- target/application.jar
- build/*
The paths
list uses Glob
from Go, and the pattern matches filepath.Match.
pattern:
{ term }
term:
'*' matches any sequence of non-Separator characters
'?' matches any single non-Separator character
'[' [ '^' ] { character-range }
']' character class (must be non-empty)
c matches character c (c != '*', '?', '\\', '[')
'\\' c matches character c
character-range:
c matches character c (c != '\\', '-', ']')
'\\' c matches character c
lo '-' hi matches character c for lo <= c <= hi
The Go documentation states that the pattern may describe hierarchical names such as /usr/*/bin/ed
(assuming the Separator is '/').
Everything must be relative to the work space root directory. |
attach_workspace
Special step used to attach the workflow’s workspace to the current container. The full contents of the workspace are downloaded and copied into the directory the workspace is being attached at. For more information on using workspaces, see the Using workspaces page.
Key | Required | Type | Description |
---|---|---|---|
| Y | String | Directory to attach the workspace to. |
Workspace storage retention can be customized on the CircleCI web app by navigating to .
Example:
- attach_workspace:
at: /tmp/workspace
The lifetime of artifacts, workspaces, and caches can be customized on the CircleCI web app by navigating to . Here you can control the storage retention periods for these objects. If no storage period is set, the default storage retention period of artifacts is 30 days, while the default storage retention period of workspaces and caches is 15 days. |
add_ssh_keys
Special step that adds SSH keys from a project’s settings to a container. Also configures SSH to use these keys. For more information on SSH keys see the Create additional GitHub SSH keys page.
Using server? only MD5 fingerprints are supported. In CircleCI in | the MD5 fingerprint will be visible. SHA256 support is planned for an upcoming server release.
Key | Required | Type | Description |
---|---|---|---|
| N | List | List of fingerprints corresponding to the keys to be added (default: all keys added) |
steps:
- add_ssh_keys:
fingerprints:
- "b7:35:a6:4e:9b:0d:6d:d4:78:1e:9a:97:2a:66:6b:be"
- "SHA256:NPj4IcXxqQEKGXOghi/QbG2sohoNfvZ30JwCcdSSNM0"
Even though CircleCI uses ssh-agent to sign all added SSH keys, you must use the add_ssh_keys key to actually add keys to a container. |
Using pipeline
values
Pipeline values are available to all pipeline configurations and can be used without previous declaration. For a list of pipeline values, see the Pipeline values and parameters page.
Example:
version: 2.1
jobs:
build:
docker:
- image: cimg/node:17.2.0
environment:
IMAGETAG: latest
working_directory: ~/main
steps:
- run: echo "This is pipeline ID << pipeline.id >>"
circleci_ip_ranges
Enables jobs to go through a set of well-defined IP address ranges. See IP ranges for details.
Example:
version: 2.1
jobs:
build:
circleci_ip_ranges: true # opts the job into the IP ranges feature
docker:
- image: curlimages/curl
steps:
- run: echo “Hello World”
workflows:
build-workflow:
jobs:
- build
workflows
Used for orchestrating all jobs. Each workflow consists of the workflow name as a key and a map as a value. A name should be unique within the current config.yml
. The top-level keys for the Workflows configuration are version
and jobs
. For more information, see the Using Workflows to Orchestrate Jobs page.
version
The workflows version key is not required for version: 2.1 configuration |
The Workflows version
field is used to issue warnings for deprecation or breaking changes.
Key | Required | Type | Description |
---|---|---|---|
| Y if config version is | String | Should currently be |
<workflow_name
>
A unique name for your workflow.
triggers
Specifies which triggers will cause this workflow to be executed. Default behavior is to trigger the workflow when pushing to a branch.
Key | Required | Type | Description |
---|---|---|---|
| N | Array | Should currently be |
workflows:
nightly:
triggers:
- schedule:
cron: "0 0 * * *"
filters:
branches:
only:
- main
- beta
jobs:
- test
schedule
Scheduled workflows are not available for projects integrated through the GitHub App, GitLab or Bitbucket Data Center. |
The scheduled workflows feature is set to be deprecated. Using scheduled pipelines rather than scheduled workflows offers several benefits. Visit the scheduled pipelines migration guide to find out how to migrate existing scheduled workflows to scheduled pipelines. If you would like to set up scheduled pipelines from scratch, visit the Scheduled pipelines page. |
A workflow may have a schedule
indicating it runs at a certain time, for example a nightly build that runs every day at 12am UTC:
workflows:
nightly:
triggers:
- schedule:
cron: "0 0 * * *"
filters:
branches:
only:
- main
- beta
jobs:
- test
cron
The cron
key is defined using POSIX crontab
syntax.
Key | Required | Type | Description |
---|---|---|---|
| Y | String | See the crontab man page. |
workflows:
nightly:
triggers:
- schedule:
cron: "0 0 * * *"
filters:
branches:
only:
- main
- beta
jobs:
- test
filters
Trigger filters can have the key branches
.
Key | Required | Type | Description |
---|---|---|---|
| Y | Map | A map defining rules for execution on specific branches |
workflows:
nightly:
triggers:
- schedule:
cron: "0 0 * * *"
filters:
branches:
only:
- main
- beta
jobs:
- test
branches
The branches
key controls whether the current branch should have a schedule trigger created for it, where current branch is the branch containing the config.yml
file with the trigger
stanza. That is, a push on the main
branch will only schedule a workflow for the main
branch.
Branches can have the keys only
and ignore
which each map to a single string naming a branch. You may also use regular expressions to match against branches by enclosing them with `/’s, or map to a list of such strings. Regular expressions must match the entire string.
-
Any branches that match
only
will run the job. -
Any branches that match
ignore
will not run the job. -
If neither
only
norignore
are specified then all branches will run the job. If bothonly
andignore
are specified, theonly
is used andignore
will have no effect.
workflows:
commit:
jobs:
- test
- deploy
nightly:
triggers:
- schedule:
cron: "0 0 * * *"
filters:
branches:
only:
- main
- /^release\/.*/
jobs:
- coverage
Key | Required | Type | Description |
---|---|---|---|
| Y | Map | A map defining rules for execution on specific branches |
| N | String, or List of Strings | Either a single branch specifier, or a list of branch specifiers |
| N | String, or List of Strings | Either a single branch specifier, or a list of branch specifiers |
1: One of either only
or ignore
branch filters must be specified. If both are present, only
is used.
Using when
in workflows
Using when or unless under workflows is supported in version: 2.1 configuration. Workflows are always run unless there is a when or unless filter that prevents the workflow from being run. If you want a workflow to run in every pipeline, do not add a when or unless filter. |
You may use a when
clause (the inverse clause unless
is also supported) under a workflow declaration with a logic statement to determine whether or not to run that workflow.
The example configuration below uses a pipeline parameter, run_integration_tests
to drive the integration_tests
workflow.
version: 2.1
parameters:
run_integration_tests:
type: boolean
default: false
workflows:
integration_tests:
when: << pipeline.parameters.run_integration_tests >>
jobs:
- mytestjob
jobs:
...
This example prevents the workflow integration_tests
from running unless the tests are invoked explicitly when the pipeline is triggered with the following in the POST
body:
{
"parameters": {
"run_integration_tests": true
}
}
Refer to the Workflows for more examples and conceptual information.
jobs
A job can have the keys requires
, name
, context
, type
, and filters
.
Key | Required | Type | Description |
---|---|---|---|
| Y | List | A list of jobs to run with their dependencies |
<job_name
>
A job name that exists in your config.yml
.
requires
Jobs are run concurrently by default, so you must explicitly require any dependencies by their job name if you need some jobs to run sequentially.
Key | Required | Type | Description |
---|---|---|---|
| N | List | A list of jobs that must succeed for the job to start. Note: When jobs in the current workflow that are listed as dependencies are not executed (due to a filter function for example), their requirement as a dependency for other jobs will be ignored by the requires option. However, if all dependencies of a job are filtered, then that job will not be executed either. |
name
The name
key can be used to invoke reusable jobs across any number of workflows. Using the name key ensures numbers are not appended to your job name (for example, sayhello-1 , sayhello-2, etc.). The name you assign to the name
key needs to be unique, otherwise the numbers will still be appended to the job name.
Key | Required | Type | Description |
---|---|---|---|
| N | String | A replacement for the job name. Useful when calling a job multiple times. If you want to invoke the same job multiple times, and a job requires one of the duplicate jobs, this key is required. (2.1 only) |
context
Jobs may be configured to use global environment variables set for an organization, see the Contexts document for adding a context in the application settings.
Key | Required | Type | Description |
---|---|---|---|
| N | String/List | The name of the context(s). The initial default name is |
type
A job may have a type
of approval
indicating it must be manually approved before downstream jobs may proceed. For more information see the Using workflows to orchestrate jobs page.
Jobs run in the dependency order until the workflow processes a job with the type: approval
key followed by a job on which it depends, for example:
workflows:
my-workflow:
jobs:
- build
- test:
requires:
- build
- hold:
type: approval
requires:
- test
- deploy:
requires:
- hold
An approval job can have any name. In the example above the approval job is named hold
. The name you choose for an approval job should not be used to define a job in the main configuration. An approval job only exists as a workflow orchestration devise.
filters
Filter job execution within a workflow based on the following:
-
Branch
-
Tag
-
Expression-based condition
Job filters can have the keys branches
or tags
.
Workflows will ignore job-level branching. If you use job-level branching and later add workflows, you must remove the branching at the job level and instead declare it in the workflows section of your config.yml . |
Key | Required | Type | Description |
---|---|---|---|
| N | Map | A map or string to define rules for job execution. Branch and tag filters require a map. Expression-based filters require a string. |
The following is an example of how the CircleCI documentation project uses a regular expression to filter running a job in a workflow only on a specific branch:
# ...
workflows:
build-deploy:
jobs:
- js_build
- build_server_pdfs: # << the job to conditionally run based on the filter-by-branch-name.
filters:
branches:
only: /server\/.*/ # the job build_server_pdfs will only run when the branch being built starts with server/
You can read more about using regular expressions in your config in the Using workflows to schedule jobs page.
Expression-based job filters
Expression-based job filters allow you to conditionally run jobs based on the following:
An expression-based job filter is a rule that is evaluated against pipeline values and parameters to decide whether a job should run.
Using expression-based job filters is one way to optimize your pipelines to lower costs, decrease time to feedback, or run specific jobs based on the context of the source of change.
workflows:
deploy:
jobs:
- init-service
- build-service-image:
requires:
- init-service
- dry-run-service:
requires:
- init-service
filters: pipeline.git.branch != "main" and pipeline.git.branch != "canary"
- publish-service:
requires:
- build-service-image
- test-service
filters: pipeline.git.branch == "main" or pipeline.git.tag starts-with "release"
- deploy-service:
context:
- org-global
requires:
- publish-service
filters: pipeline.git.branch == "main" and pipeline.git.commit.subject starts-with "DEPLOY:"
Examples
Only run the job on the project’s main
branch:
filters: pipeline.git.branch == "main"
Only run the job on the project’s main
branch, or branches starting with integration-test
:
filters: pipeline.git.branch == "main" or pipeline.git.branch starts-with "integration-test"
Only run the job on the main
branch, and disallow use with pipelines triggered with unversioned configuration:
filters: pipeline.git.branch == "main" and not (pipeline.config_source starts-with "api")
Use pipeline parameters and the pipeline value pipeline.git.branch
to run a job only on specific branches or when triggered via the API with a pipeline parameter set to true:
version: 2.1
parameters:
run-storybook-tests:
type: boolean
default: false
...
# jobs configuration ommitted for brevity
workflows:
build:
jobs:
- setup
- storybook-tests:
requires:
- setup
filters: |
pipeline.parameters.run-storybook-tests
or pipeline.git.branch == "dry-run-deploy"
or pipeline.git.branch starts-with "deploy"
You can use the API to trigger a pipeline with a pipeline parameter set to true:
curl -X POST https://circleci.com/api/v2/project/circleci/<org-id>/<project-id>/pipeline/run \
--header "Circle-Token: $CIRCLE_TOKEN" \
--header "content-type: application/json" \
--data {
"definition_id": "<pipeline-definition-id>",
"config": {"branch": "<your-branch-name>"},
"checkout": {"branch": "<your-branch-name>"},
"parameters": {"run-storybook-tests": "true"}
}
Operators
The operators you can use for expression-based job filters are described in the following table. You can also group sub-expressions with parentheses (
, )
. as in the examples above.
Operator type | Operators | Description |
---|---|---|
Logical |
| These are short-circuiting boolean operators. |
Equality |
| String, numeric, and boolean equality. If the operands are of different types then |
Equality |
| String prefix equality, |
Numeric comparison |
| Numeric comparisons. It is an error to use a non-numeric type as an operand. |
Negation |
| Boolean negation. Note that
|
branches
The branches filter can have the keys only
and ignore
, which map to a single string naming a branch. You may also use regular expressions to match against branches by enclosing them with slashes, or map to a list of such strings. Regular expressions must match the entire string.
-
Any branches that match
only
will run the job. -
Any branches that match
ignore
will not run the job. -
If neither
only
norignore
are specified then all branches will run the job. -
If both
only
andignore
are specified theonly
is considered beforeignore
.
Key | Required | Type | Description |
---|---|---|---|
| N | Map | A map defining rules for execution on specific branches. |
| N | String, or list of strings | Either a single branch specifier, or a list of branch specifiers. |
| N | String, or list of strings | Either a single branch specifier, or a list of branch specifiers. |
workflows:
dev_stage_pre-prod:
jobs:
- test_dev:
filters: # using regex filters requires the entire branch to match
branches:
only: # only branches matching the below regex filters will run
- dev
- /user-.*/
- test_stage:
filters:
branches:
only: stage
- test_pre-prod:
filters:
branches:
only: /pre-prod(?:-.+)?$/
tags
CircleCI does not run workflows for tags unless you explicitly specify tag filters. Additionally, if a job requires any other jobs (directly or indirectly), you must specify tag filters for those jobs.
Tags can have the keys only
and ignore
. You may also use regular expressions to match against tags by enclosing them with slashes, or map to a list of such strings. Regular expressions must match the entire string. Both lightweight and annotated tags are supported.
-
Any tags that match
only
will run the job. -
Any tags that match
ignore
will not run the job. -
If neither
only
norignore
are specified then the job is skipped for all tags. -
If both
only
andignore
are specified theonly
is considered beforeignore
.
Key | Required | Type | Description |
---|---|---|---|
| N | Map | A map defining rules for execution on specific tags |
| N | String, or List of Strings | Either a single tag specifier, or a list of tag specifiers |
| N | String, or List of Strings | Either a single tag specifier, or a list of tag specifiers |
For more information, see the Executing workflows for a git tag section of the Workflows page.
workflows:
untagged-build:
jobs:
- build
tagged-build:
jobs:
- build:
filters:
tags:
only: /^v.*/
matrix
The matrix key is supported in version: 2.1 configuration |
The matrix
stanza allows you to run a parameterized job multiple times with different arguments. For more information see the how-to guide on Using Matrix Jobs. In order to use the matrix
stanza, you must use parameterized jobs.
Key | Required | Type | Description |
---|---|---|---|
| Y | Map | A map of parameter names to every value the job should be called with |
| N | List | A list of argument maps that should be excluded from the matrix |
| N | String | An alias for the matrix, usable from another job’s |
Example:
The following is a basic example of using matrix jobs.
workflows:
workflow:
jobs:
- build:
matrix:
parameters:
version: ["0.1", "0.2", "0.3"]
platform: ["macos", "windows", "linux"]
This expands to 9 different build
jobs, and could be equivalently written as:
workflows:
workflow:
jobs:
- build:
name: build-macos-0.1
version: 0.1
platform: macos
- build:
name: build-macos-0.2
version: 0.2
platform: macos
- build:
name: build-macos-0.3
version: 0.3
platform: macos
- build:
name: build-windows-0.1
version: 0.1
platform: windows
- ...
Excluding sets of parameters from a matrix
Sometimes you may wish to run a job with every combination of arguments except some value or values. You can use an exclude
stanza to achieve this:
workflows:
workflow:
jobs:
- build:
matrix:
parameters:
a: [1, 2, 3]
b: [4, 5, 6]
exclude:
- a: 3
b: 5
The matrix above would expand into 8 jobs: every combination of the parameters a
and b
, excluding {a: 3, b: 5}
Dependencies and matrix jobs
To require
an entire matrix (every job within the matrix), use its alias
. The alias
defaults to the name of the job being invoked.
workflows:
workflow:
jobs:
- deploy:
matrix:
parameters:
version: ["0.1", "0.2"]
- another-job:
requires:
- deploy
This means that another-job
will require both deploy jobs in the matrix to finish before it runs.
Additionally, matrix jobs expose their parameter values via << matrix.* >>
which can be used to generate more complex workflows. For example, here is a deploy
matrix where each job waits for its respective build
job in another matrix.
workflows:
workflow:
jobs:
- build:
name: build-v<< matrix.version >>
matrix:
parameters:
version: ["0.1", "0.2"]
- deploy:
name: deploy-v<< matrix.version >>
matrix:
parameters:
version: ["0.1", "0.2"]
requires:
- build-v<< matrix.version >>
This workflow will expand to:
workflows:
workflow:
jobs:
- build:
name: build-v0.1
version: 0.1
- build:
name: build-v0.2
version: 0.2
- deploy:
name: deploy-v0.1
version: 0.1
requires:
- build-v0.1
- deploy:
name: deploy-v0.2
version: 0.2
requires:
- build-v0.2
pre-steps
and post-steps
Pre-steps and post-steps are supported in version: 2.1 configuration |
Every job invocation in a workflow may optionally accept two special arguments: pre-steps
and post-steps
.
Steps under pre-steps
are executed before any of the other steps in the job. The steps under post-steps
are executed after all of the other steps.
Pre and post steps allow you to execute steps in a given job without modifying the job. This is useful, for example, to run custom setup steps before job execution.
version: 2.1
jobs:
bar:
machine:
image: ubuntu-2004:202107-02
steps:
- checkout
- run:
command: echo "building"
- run:
command: echo "testing"
workflows:
build:
jobs:
- bar:
pre-steps: # steps to run before steps defined in the job bar
- run:
command: echo "install custom dependency"
post-steps: # steps to run after steps defined in the job bar
- run:
command: echo "upload artifact to s3"
Logic statements
Certain dynamic configuration features accept logic statements as arguments. Logic statements are evaluated to boolean values at configuration compilation time, that is, before the workflow is run. The group of logic statements includes:
Type | Arguments | true if | Example |
---|---|---|---|
YAML literal | None | is truthy |
|
YAML alias | None | resolves to a truthy value | *my-alias |
None | resolves to a truthy value |
| |
None | resolves to a truthy value |
| |
| N logic statements | all arguments are truthy |
|
| N logic statements | any argument is truthy |
|
| 1 logic statement | the argument is not truthy |
|
| N values | all arguments evaluate to equal values |
|
|
|
|
|
The following logic values are considered falsy:
-
false
-
null
-
0
-
NaN
-
empty strings ("")
-
statements with no arguments
All other values are truthy. Also note that using logic with an empty list will cause a validation error.
Logic statements always evaluate to a boolean value at the top level, and coerce as necessary. They can be nested in an arbitrary fashion, according to their argument specifications, and to a maximum depth of 100 levels.
matches
uses Java regular expressions for its pattern
. A full match pattern must be provided, prefix matching is not an option. Though, it is recommended to enclose a pattern in ^
and $
to avoid accidental partial matches.
When using logic statements at the workflow level, do not include the condition: key (the condition key is only needed for job level logic statements). |
Logic statement examples
workflows:
my-workflow:
when:
or:
- equal: [ main, << pipeline.git.branch >> ]
- equal: [ staging, << pipeline.git.branch >> ]
workflows:
my-workflow:
when:
and:
- not:
matches:
pattern: "^main$"
value: << pipeline.git.branch >>
- or:
- equal: [ canary, << pipeline.git.tag >> ]
- << pipeline.parameters.deploy-canary >>
version: 2.1
executors:
linux-13:
docker:
- image: cimg/node:13.13
macos: &macos-executor
macos:
xcode: 14.2.0
jobs:
test:
parameters:
os:
type: executor
node-version:
type: string
executor: << parameters.os >>
steps:
- checkout
- when:
condition:
equal: [ *macos-executor, << parameters.os >> ]
steps:
- run: echo << parameters.node-version >>
- run: echo 0
workflows:
all-tests:
jobs:
- test:
os: macos
node-version: "13.13.0"
Example full configuration
Using Docker? Authenticating Docker pulls from image registries is recommended when using the Docker execution environment. Authenticated pulls allow access to private Docker images, and may also grant higher rate limits, depending on your registry provider. For further information see Using Docker authenticated pulls. |
version: 2.1
jobs:
build:
docker:
- image: ubuntu:14.04
- image: mongo:2.6.8
command: [mongod, --smallfiles]
- image: postgres:14.2
# some containers require setting environment variables
environment:
POSTGRES_USER: user
- image: redis@sha256:54057dd7e125ca41afe526a877e8bd35ec2cdd33b9217e022ed37bdcf7d09673
- image: rabbitmq:3.5.4
environment:
TEST_REPORTS: /tmp/test-reports
working_directory: ~/my-project
steps:
- checkout
- run:
command: echo 127.0.0.1 devhost | sudo tee -a /etc/hosts
# Create Postgres users and database
# Note the YAML heredoc '|' for nicer formatting
- run: |
sudo -u root createuser -h localhost --superuser ubuntu &&
sudo createdb -h localhost test_db
- restore_cache:
keys:
- v1-my-project-{{ checksum "project.clj" }}
- v1-my-project-
- run:
environment:
SSH_TARGET: "localhost"
TEST_ENV: "linux"
command: |
set -xu
mkdir -p ${TEST_REPORTS}
run-tests.sh
cp out/tests/*.xml ${TEST_REPORTS}
- run: |
set -xu
mkdir -p /tmp/artifacts
create_jars.sh << pipeline.number >>
cp *.jar /tmp/artifacts
- save_cache:
key: v1-my-project-{{ checksum "project.clj" }}
paths:
- ~/.m2
# Save artifacts
- store_artifacts:
path: /tmp/artifacts
destination: build
# Upload test results
- store_test_results:
path: /tmp/test-reports
deploy-stage:
docker:
- image: ubuntu:14.04
working_directory: /tmp/my-project
steps:
- run:
name: Deploy if tests pass and branch is Staging
command: ansible-playbook site.yml -i staging
deploy-prod:
docker:
- image: ubuntu:14.04
working_directory: /tmp/my-project
steps:
- run:
name: Deploy if tests pass and branch is Main
command: ansible-playbook site.yml -i production
workflows:
build-deploy:
jobs:
- build:
filters:
branches:
ignore:
- develop
- /feature-.*/
- deploy-stage:
requires:
- build
filters:
branches:
only: staging
- deploy-prod:
requires:
- build
filters:
branches:
only: main