Run a job in a container on your machine with Docker
On This Page
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.
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_NAME
If 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_NAME
The 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 build
The 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 Postgres 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.
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.
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
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.
For security reasons, encrypted environment variables 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 build
If you have multiple environment variables, you must use the flag for each variable, for example:
circleci build -e VAR1=FOO -e VAR2=BAR
Help make this document better
This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.
- Suggest an edit to this page (please read the contributing guide first).
- To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
- CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.
Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.
You can also visit our support site to find support articles, community forums, and training resources.
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.