An Installer for Drupal 8 and GitLab CI

It’s been great to see the activity and excitement around the repository where we host one-line installers to connect Drupal 8 projects with popular continuous integration tools. Since the Drupal and GitLab partnership landed, we have been asked about when we would write an installer for GitLab. This article announces such integration.

🤓 If you want to dive right into the code, here are the installer instructions and here is the sample project repository.

GitLab: more than CI

I am impressed with what the GitLab folks have built. While CircleCI and Travis CI are continuous integration and delivery tools, GitLab offers a holistic approach to DevOps, with a set of tools to manage the development life cycle.

Project setup

Here is the setup required to run the GitLab pipeline in your project:

1. Create a Drupal 8 project via the composer template command.
2. Run the Drupal installation.
3. Add web/sites/default/settings.php to the repository and uncomment the section that loads a settings.local.php file if it exists.
4. Run the GitLab CI installer, which will add all the required files to run the pipeline when code changes are pushed to GitLab.
5. Create a database dump. Then follow the instructions in the article, Achieve Rocketship-Fast Jobs in CircleCI by Preinstalling the Database, to install the database in a Docker MariaDB image.

The pipeline in action

A pipeline is the heart of GitLab’s continuous integration: a file where what it should do and when should it do it is defined. Here is the resulting pipeline from creating a merge request for the sample Drupal 8 project that I used to integrate with GitLab:

We configured the above pipeline, so there is a Build job that prepares the environment and then hands it off to the other jobs that perform the actual test running and evaluating. The graph above shows that all the jobs passed, hence the green marks. Clicking on the Jobs tab shows the following screen with the timings of each job plus the code coverage percentage:

In the next section, you will see the contents of the file that defines the above pipeline.

The .gitlab-ci.yml file

Pipelines are defined in a file called .gitlab-ci.yml which is located at the root of the repository and uses YAML syntax to define the stages, steps, and scripts. Here is the first half of the pipeline that powers the screenshots of the above section, which contains a few definitions and templates:

And here is the second half, where we defined the jobs of the Test stage. Notice the use of the extends keyword, which is a GitLab CI feature that allows reusing and overriding in YAML files.

The script section of each job is simple as it relies on Robo, a PHP task runner to perform tasks such as running a test suite. The next section explains how these tasks work.

Robo tasks

In the previous screenshot, you saw that each job calls a Robo task such as vendor/bin/robo run:code-sniffer. Robo is a PHP task runner used by projects such as Drush.

Using Robo simplifies the gitlab-ci.yml file by turning job scripts into tasks that can be reused in other places such as deployments and local development. Here is an example of the task that checks a Drupal 8 project to ensure it follows Drupal coding standards and best practices:

Where is the database?

The drupal8:existing_site_tests job requires the project’s database to run its tests. Instead of hosting a database dump in the cloud so that CircleCI could download it and install it (like we did in the CircleCI integration with Drupal 8), we pre-installed the database in a MariaDB Docker image. This made jobs simpler and faster since less setup is required to get the database running for a job.

If you're curious about how to set up the MariaDB Docker image for your project’s database, you can find the details in the article, Achieve Rocketship-Fast Jobs in CircleCI by Preinstalling the Database. We used the scripts for this article and pushed the resulting Docker image to GitLab’s Container Registry.

Running a headless browser in GitLab

To test the whole site, we opted for Moshe Weitzman’s Drupal Test Traits. These tests assume that there is a Drupal site running and are a great alternative to Behat if your team prefers to write tests in PHP instead of Gherkin.

We installed Google Chrome in the Docker image that we used to run tests, and then we wrote a Robo task that starts Chrome in the background so tests could run against the site.

If you prefer to use Selenium WebDriver, refer to the documentation at Drupal Test Traits and GitLab to set it up.

Try it out

Navigate to the drupal8ci project and follow the instructions for installing the files onto your Drupal 8 project and start running GitLab pipelines. Alternatively, copy the files that you need from the sample project.

For a list of additional jobs for your project’s pipeline, check out Jean Valverde’s Gitlab CI for Drupal 8.

Thanks to Nate Lampton, Matthew Tift, Andrew Berry, and Ellie Fanning for their feedback.