Configuration reference

Authenticate using OpenID Connect (OIDC) using the oidc_role_arn field, as follows:

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.

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:

Arm on Docker For pricing information, and a list of CircleCI Docker convenience images that support Arm resource classes, see the Resource classes page.

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

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:

-o pipefail

For example:

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 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.

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 has a very convenient shorthand syntax:

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.

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.

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:

The cron key is defined using POSIX crontab syntax.

Trigger filters can have the key 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.

¹: One of either only or ignore branch filters must be specified. If both are present, only is used.

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.

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.

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.

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:

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.

Filter job execution within a workflow based on the following:

Job filters can have the keys branches or tags.

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:

You can read more about using regular expressions in your config in the Using workflows to schedule jobs page.

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.

Examples

Only run the job on the project’s main branch:

Only run the job on the project’s main branch, or branches starting with integration-test:

Only run the job on the main branch, and disallow use with pipelines triggered with unversioned configuration:

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:

You can use the API to trigger a pipeline with a pipeline parameter set to 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.

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.

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.

For more information, see the Executing workflows for a git tag section of the Workflows page.

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.

Example:

The following is a basic example of using matrix jobs.

This expands to 9 different build jobs, and could be equivalently written as:

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:

The matrix above would expand into 8 jobs: every combination of the parameters a and b, excluding {a: 3, b: 5}

To require an entire matrix (every job within the matrix), use its alias. The alias defaults to the name of the job being invoked.

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.

This workflow will expand to:

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.