CircleCI is a continuous integration system that allows you to run your custom build process. Often times we use it as a way to run tests from our GitHub feature branches and then push the code to a Pantheon development environment once it gets approved and merged into master. It has been great to work with and has caught many issues from failed tests before they got pushed to live.

On one of the large projects we have been working on over the years, it has gotten so many tests that it started taking upwards of 30 minutes to fully complete the build process in CircleCI 1.0. This made it difficult preparing for deployments when we had several branches that got approved and were ready to get merged in. On top of that, debugging testing related issues was very time-consuming.

We recently decided to give CircleCI 2.0 a shot. The main change in this upgraded system is that it uses containers (docker) to build the environments the site is run off of. From early reports in the beta process, we were hearing how much 2.0 increased the speed of the build times.

After we got this working on our project, we were seeing build times closer to the 20-minute mark, compared to 30 minutes. We were able to move some of the setup process for the environment in the docker image, which also saved time. This was a huge improvement for the project!

Take a look at a video we recorded during one of our Drupal practice groups where I walk through the process of setting up CircleCI 2.0.

Creating a Docker Image

Using docker allows you full control over the software that is used to run your builds in CircleCI 2.0. For the project where we implemented CircleCI 2.0, this was the most time-consuming part, mainly from the specific versions of the software we were using and ironing out all of the dependencies.

I suggest using Docker Hub to manage your docker images. If you create a docker automated build, you can push changes to the docker image in a separate GitHub repo and have the image created automatically when updates are pushed. This is a huge timesaver with managing your docker image. It saves the time in having to generate the docker image and push it up locally, which can be time-consuming with large docker images.

You can take a look at the docker hub automated build and the GitHub repo we are using for this project.

Our CircleCI 2.0 Build

All of the config for CircleCI 2.0 is kept in the .circleci/config.yml file. Commands are organized into “jobs” and you can configure which jobs are run using “workflows”.

In the case of this project, I decided to organize the config in two separate jobs: one for the main build called “build” and the other for pushing code to the pantheon dev environment. We then created a workflow that will always hit the “build” job for everything, and we target the push to pantheon job to only run when code is pushed to master. This allows us to control which jobs are run for each use case.

You can view the CircleCI config file we are using on the project, along with the file we are referencing.

There are multiple ways you can organize your jobs and workflows, and it is very much project dependent. I decided to create one main job for most of the build for this project, because I most of the commands I was running depended on the docroot existing and being populated from running aquifer build and aquifer run local, and it kept the CircleCI config and docker image simpler. But you could, for example, use multiple docker images (one for your database and one with nginex). Or you could separate things into multiple jobs and share data between each job using caching.

Getting Started with CircleCI 2.0

I would first take a look at their getting started video. If you are starting a new project, the main CircleCI 2.0 documentation page is a great place to start. If you are upgrading a project from CircleCI 1.0, take a look at their migration page.

As part of getting CircleCI 2.0 setup, I found it useful to install the CircleCI Command Line Interface tool. This will allow you to validate your config file and run builds locally.

If you want to avoid having to manually rebuild the docker image with changes, I suggest creating a separate GitHub repo and then creating an automated build repo on dockerhub. That will make the image automatically get rebuilt when changes are pushed to the docker image.


CircleCI is a great continuous integration system, and CircleCI 2.0 adds a lot of value to their system. We’ve greatly reduced the time builds take to complete and has made our deployment process run much more smoothly. If you need a way to run tests and create a reliable process for deployment, you should strongly consider going with CircleCI 2.0.