Run a job in a container on your machine with Docker
The CLI enables you to run individual jobs on your local machine with Docker. This can be useful to run tests before pushing configuration changes, or debugging your build process without impacting your build queue.
Prerequisites
You will need to have Docker installed on your system, as well as the most recent version of the CLI. You will also need to have a project with a valid .circleci/config.yml file in it.
Running a job
The CLI allows you to run a single job from CircleCI on your desktop using Docker with the following command:
$ circleci local execute JOB_NAMEIf your CircleCI configuration is set to version 2.1 or greater, you must first export your configuration to process.yml, and specify it when executing with the following commands:
circleci config process .circleci/config.yml > process.yml
circleci local execute -c process.yml JOB_NAMEThe following commands will run an example build on your local machine on one of CircleCI’s demo applications:
git clone https://github.com/CircleCI-Public/circleci-demo-go.git
cd circleci-demo-go
circleci local execute buildThe commands above will run the entire build job (only jobs, not workflows, can be run locally). The CLI will use Docker to pull down the requirements for the build and then execute your CI steps locally. In this case, Golang and PostgreSQL Docker images are pulled down, allowing the build to install dependencies, run the unit tests, test the service is running, and so on.
Limitations of running jobs locally
Although running jobs locally with circleci is very helpful, there are some limitations.
Machine executor
You cannot use the machine executor in local jobs. This is because the machine executor requires an extra VM to run its jobs.
Add SSH keys
It is currently not possible to add SSH keys using the add_ssh_keys CLI command.
Workflows
The CLI tool does not provide support for running workflows. By nature, workflows leverage running jobs concurrently on multiple machines allowing you to achieve faster, more complex builds. Because the CLI is only running on your machine, it can only run single jobs (which make up parts of a workflow).
Caching and online-only Commands
Caching is not currently supported in local jobs. When you have either a save_cache or restore_cache step in your config, circleci will skip them and display a warning.
Further, not all commands may work on your local machine as they do online. For example, the Golang build reference above runs a store_artifacts step, however, local builds will not upload artifacts. If a step is not available on a local build you will see an error in the console.
Environment variables and contexts
For security reasons, encrypted environment variables or contexts configured in the web application will not be imported into local builds. As an alternative, you can specify environment variables to the CLI with the -e flag. See the output of the following command for more information.
circleci help buildIf you have multiple environment variables, you must use the flag for each variable, for example:
circleci build -e VAR1=FOO -e VAR2=BAR