Choosing an Executor Type
An executor defines an underlying technology to run your job. Currently, we provide two options:
Like any set of choices, there are tradeoffs to using one over the other. Here’s a basic comparison:
|Start time||Instant||30-60 sec|
|Build Docker images||Yes (1)||Yes|
|Full control over job environment||No||Yes|
(1) With Remote Docker.
When you choose the
docker executor, your job will run in a Docker container. You can specify the container image in
jobs: build: docker: - image: buildpack-deps:trusty
It’s also possible to specify multiple images. When you do this, all containers will run in a common network. Every exposed port will be available on
localhost from a primary container.
jobs: build: docker: - image: buildpack-deps:trusty - image: mongo:2.6.8 command: [mongod, --smallfiles] working_directory: ~/ steps: # command will execute in trusty container # and can access mongo on localhost - run: sleep 5 && nc -vz localhost 27017
In a multi-image configuration job, steps are executed in the first container listed (main container).
More details on the Docker Executor are available here.
Only public images on Docker Hub and Docker Registry are supported. If you want to work with private images/registries, please refer to Remote Docker.
Images for the Docker Executor can be specified in a few ways:
Public Images on Docker Hub
Public Docker Registries
When To Use The Docker Executor?
- your application is self-sufficient
- your application requires additional services to be tested
- your application is distributed as a Docker Image (requires using Remote Docker)
- you want to use
docker-compose(requires using Remote Docker)
- Fastest way to start a job
- Use any custom image for a job environment
- Built-in image caching
- Build, run, and publish Docker images via Remote Docker
- Limited by what is possible from within a Docker container (including our Remote Docker feature). For instance, if you require low-level access to the network or need to mount external volumes checkout the
Avoid Mutable Tags
We strongly discourage using mutable tags like
1. Mutable tags often lead to unexpected changes in your job environment.
We also can’t guarantee that mutable tags will return an up-to-date version of an image. You could specify
alpine:latest and actually get a stale cache from a month ago.
Instead, we recommend using precise image versions or digests, like
Use Custom Images
If you find yourself incurring undo increases in your run times due to installing additional tools during execution, we recommend making custom images that meet the job’s requirements, so the container will have such tools pre-loaded.
Potential Premium Feature Notice: Machine Executor
During the CircleCI 2.0 Beta we are providing early access, for no additional charge, to features (including Machine Executor) that may be available for additional fees after the Beta. We welcome your feedback on this and all other aspects of CircleCI 2.0.
When you choose the
machine executor, your job will run in a dedicated, ephemeral Virtual Machine (VM). To use the machine executor, simply set the
machine key to
jobs: build: machine: true
The VM will run Ubuntu 14.04 with a few additional tools installed. It isn’t possible to specify other images.
When To Use the Machine Executor?
- Your application requires full access to OS resources
- Gives full control over job environment
- Takes additional time to create VM
- Only the default image is supported; your job may require additional provisioning.