Continuous Integration for Drupal 8 with CircleCI

This article is the first in a series about different Continuous Integration implementations for Drupal 8 projects. Each installment will pick a CI technology and go over its pros and cons for implementing the following set of jobs when someone creates a pull request:

• Run unit and kernel tests.
• Generate a PHPUnit coverage report.
• Check Drupal's coding standards.
• Update the database and run Behat tests.

In this article, we will start with CircleCI, a SaaS platform. Thanks to work initiated by Andrew Berry at drupal_tests—if you maintain a Drupal 8 module, check it out—I can present you a single-command installer to get your Drupal 8 project started with Continuous Integration using CircleCI.

There is a repository that contains the installer script where we are working on the different CI implementations, plus a demo Drupal project to see them in action.

Setup

Here is a clip where I take a vanilla Drupal 8 project created with composer-project, I run the installer and commit the files, and when I allow CircleCI to watch the repository I see the jobs running:

For details on how to run the installation script and connect your repository with CircleCI, have a look at the repository's README.

Killer features

Once you have the setup in place, your project will benefit right away from the following features:

Less infrastructure to maintain

When code is pushed to a GitHub repository, CircleCI takes care of spinning up and tearing down containers for each of the jobs that you have defined in the CircleCI configuration file. CircleCI provides a set of pre-built images for you to use on your project but you can use a custom Docker image if you need it. For example, here is the Dockerfile that the installer script uses:

# This is the parent image, located at https://hub.docker.com/_/drupal
FROM drupal:8.4-apache

# Install libraries and extensions.
RUN apt-get update && apt-get install -y \
  imagemagick \
  libmagickwand-dev \
  mariadb-client \
  sudo \
  vim \
  wget \
  && docker-php-ext-install mysqli \
  && docker-php-ext-install pdo \
  && docker-php-ext-install pdo_mysql

# Remove the vanilla Drupal project that comes with the parent image.
RUN rm -rf /var/www/html/*

# Change docroot since we use Composer's drupal-project.
RUN sed -ri -e 's!/var/www/html!/var/www/html/web!g' /etc/apache2/sites-available/*.conf
RUN sed -ri -e 's!/var/www!/var/www/html/web!g' /etc/apache2/apache2.conf /etc/apache2/conf-available/*.conf

# Install composer.
RUN wget https://raw.githubusercontent.com/composer/getcomposer.org/f3333f3bc20ab8334f7f3dada808b8dfbfc46088/web/installer -O - -q | php -- --quiet
RUN mv composer.phar /usr/local/bin/composer

# Put a turbo on composer.
RUN composer global require hirak/prestissimo

# Install XDebug.
RUN pecl install xdebug-2.5.5 \
    && docker-php-ext-enable xdebug

# Install Robo CI.
# @TODO replace the following URL by http://robo.li/robo.phar when the Robo team fixes it.
RUN wget https://github.com/consolidation/Robo/releases/download/1.1.5/robo.phar
RUN chmod +x robo.phar && mv robo.phar /usr/local/bin/robo

# Install Dockerize.
ENV DOCKERIZE_VERSION v0.6.0
RUN wget https://github.com/jwilder/dockerize/releases/download/$DOCKERIZE_VERSION/dockerize-linux-amd64-$DOCKERIZE_VERSION.tar.gz \
    && tar -C /usr/local/bin -xzvf dockerize-linux-amd64-$DOCKERIZE_VERSION.tar.gz \
    && rm dockerize-linux-amd64-$DOCKERIZE_VERSION.tar.gz

# Install ImageMagic to take screenshots.
RUN pecl install imagick \
    && docker-php-ext-enable imagick

Status badges

By adding a CircleCI status badge to your project’s README file, you can check whether the main branch is stable or not:

This is useful when creating a new release. If the badge is red, then you need to investigate what’s going on. Beware, there is an open bug in CircleCI that may display the green PASSED badge even when one of the jobs in a workflow has failed. Until this gets fixed, click on the badge to double check that everything passes.

Version control

CircleCI’s jobs live within the project repository under the .circleci directory, which makes it easy to track changes in the jobs and make them evolve along with the project.

Intelligent reporting

CircleCI is intelligent at presenting job artifacts. Here are some screenshots:

Failed tests

By storing test results as artifacts, CircleCI can parse them and present them in the browser:

Links to screenshots taken by Behat

By using the Behat Screenshot extension and storing the screenshots as job artifacts, we can see them as a list of links in the browser:

Here is what we see when we click on the highlighted link above:

Coding standard violations

CircleCI can parse the Code Sniffer report and present a summary of Drupal coding standard violations:

Test coverage reports

By generating an HTML PHPUnit report and exposing it as an artifact, we can see a link to the report at the CircleCI web interface:

The highlighted link above shows the following report which describes how much of the code is covered by tests:

Running CircleCI jobs locally

CircleCI offers a command line interface for running jobs locally. This is a big time saver as it gives you a chance to test and debug a job locally before pushing your changes.

Ready to take off!

Do you have a Drupal 8 project and want to try Continuous Integration with CircleCI? If so, follow the instructions at the Drupal8CI repository and start writing tests and getting the jobs to pass. If you find issues or add improvements, please either post a comment here or contribute them to the repository. Happy CI-ing!

Acknowledgements

• Andrew Berry, for teaching me so much about Docker and CircleCI.
• James Sansbury, for his editorial and technical feedback, plus his Bash-fu.
• The Draco team at Turner, for allowing me to add continuous integration to their development workflow.