DrupalEasy: Test-driving GitLab CI templates for Drupal contributed modules

Earlier this year, the Drupal Association (DA) and various community contributors announced the general availability of GitLab CI (Continuous Integration) for Drupal contributed modules. The goal of this project is to replace the existing, bespoke, Drupal CI for running automated tests for both Drupal core and contributed projects with GitLab's existing CI tools, thus saving community and DA resources in the long-term. 

For contributed module maintainers, this means being able to specify more flexible tests and code validations, depending on the module's unique needs. 

Much of this functionality will be made readily available to module maintainers via GitLab templates that offer a rock-solid starting point for module maintainers. 

What can GitLab CI do?

First, some basics. The general idea is that for every commit to a contributed module project (including on issue forks,) GitLab CI will run a maintainer-defined process to run various checks on the code. These checks normally include validation steps like ensuring the project's composer.json file is valid, coding standard checks via phpcs, and static code analysis checks via PhpStan. The checks will often include testing steps that run the module's PhpUnit tests in various Drupal environments (different versions of Drupal core and PHP.)

By default, these checks - called jobs in GitLab CI parlance - are divided into three stages: build, validate, and test.

Upon completion of the pipeline (all of the defined jobs in all the stages), GitLab CI will display the results. The previous image shows a completed passing pipeline for the Markdown Easy module (note that I opted the Markdown Easy module into additional jobs - more on that below.)

If any of the jobs fail, then the project's contributors have access to detailed logs to help diagnose and correct any issues. Module maintainers can also decide which, if any, failures are not deal-breakers and decide to accept the changes anyway. It is clear that the system was built with flexibility in mind.

How does a module maintainer get started?

This is the best part - it's ridiculously easy. The DA and community contributors have created a set of templates to get you started with a basic pipeline. From the GitLab interface for a contributed module project (via https://git.drupalcode.org/,) all a maintainer has to do it click to add a new file, name it ".gitlab-ci.yml" and a "Template" dropdown will automagically appear for them to select the template:

Once the template is selected, all the maintainer has to do is commit the file to the repository and the module will have a basic pipeline up-and-running.

The basic pipeline provides both validation and PhpUnit jobs in the current version of Drupal core. 

But wait, there's more!

Want to run more tests against different versions of Drupal core (past or present) or versions of PHP? The variables template includes documentation on variable overrides to add/remove/modify pre-defined jobs.

Two of the most useful groups of variables provided by the Drupal GitLab CI templates are of the form SKIP_* and OPT_IN_* - these allow module maintainers to easily skip some jobs and opt-in to others. For example, want to skip the PhpStan validate job? Simply add the following to your module's .gitlab-ci.yml:

For an example of the OPT_IN_* variables, let's go back to the initial image above for Markdown Easy, all of those jobs shown were run by adding only the following to the module's .gitlab-ci.yml file:

OPT_IN_TEST_PREVIOUS_MAJOR refers to the previous major version of Drupal core (Drupal 9).

But wait (again,) there's even more!

Because all of this stuff is built on-top of out-of-the-box Gitlab CI functionality, module maintainers who are comfortable with .gitlab-ci.yml syntax can implement any CI process they can dream up. In the past few weeks, there have been discussions (and successes) of adding Yarn, generating GitLab pages that generate a documentation page for the module, and more!

What's the downside?

As far as I can tell, there are at least two potential issues that the DA and contributors are keeping their eyes on:

1. Change is hard. A big effort is going to be required to get module maintainers to switch to this new way of doing things. Luckily, this new way has a lot more flexibility, so that will definitely help.
2. Running Gitlab CI pipelines isn't free - the DA is spending thousands of dollars each month to accommodate this functionality (granted, Drupal CI wasn't free either.) The hope is that Gitlab CI will provide much higher levels of efficiency over Drupal CI (many speed improvements have already been made and more are being worked on) thus decreasing the cost. But, if it is easier for contrib module maintainers to run more tests, then that could have the opposite effect. I suspect that at some point, module maintainers will be provided some guidance as to how to minimize their CI "footprint". While the DA can control some of this from the templates defining the rules for when a pipeline runs, it is important that maintainers stick to these guidelines and not overuse GitLab CI by adding scheduled pipelines or other resource intensive pipelines.

Is this a finished product?

Absolutely not. The DA and contributors have regular Gitlab Acceleration Initiative meetings (normally every-other-week) in the #gitlab channel of the Drupal Slack workspace. Also, the issue queue is the place where most of contrib work happens; so file an issue, work on an existing one, test where possible to help accelerate even further.

Much of the recent effort has been toward adding features (like PhpStan and Drupal 7 support) to the default templates as well as looking for ways to optimize the pipeline for both speed and resources ($$$.)

Thanks so much to Fran Garcia-Linares, one of the main developers of the Drupal GitLab CI templates, for reviewing (and adding to!) this blog post.