Configuration

GitLab Runner

To setup a GitLab runner, they need to be installed first - see also our Ansible role. Then go to the Drupal project on GitLab into Settings / CI/CD / Runners and follow the instructions there. Make sure that the runner gets tagged with default in GitLab.

As a result, a file /etc/gitlab-runner/config.toml get created and this should be edited to look like this:

[[runners]]
  name = "Name of runner"
  url = "https://gitlab.lakedrops.com/"
  token = "TOKEN"
  executor = "docker"
  [runners.cache]
    [runners.cache.s3]
    [runners.cache.gcs]
  [runners.docker]
    tls_verify = false
    image = "registry.lakedrops.com/docker/gitlab-drupal-ci:php-7.4"
    privileged = true
    disable_entrypoint_overwrite = false
    oom_kill_disable = false
    disable_cache = false
    volumes = ["/var/run/docker.sock:/var/run/docker.sock", "/cache"]
    cache_dir = "/cache"
    shm_size = 0

The image is tagged for the PHP version the project uses. For projects with different PHP versions a different GitLab runner should be configured or the image being overwritten for each task in the .gitlab-ci.yml of the respective project.

GitLab Variables

Some variables are required for proper access control, and you have to provide them in the project configuration by going to Settings / CI/CD / Variables and adding these variables:

• SSH_PRIVATE_KEY: A private key being generated elsewhere just for this purpose. This is necessary for cloning private Git repositories.
• GITLAB_ACCESS_TOKEN: For authenticating with the LakeDrops Gitlab package repository, you have to create an access tokeb for the user who runs the pipeline and provide it in this variable.

GitLab CI instructions in Drupal project

The Drupal project should be setup with the Drupal Development Environment composer plugin and then get a .gitlab-ci.yml file for the pipeline configuration:

variables:
  PROJECT_NAME: <project_name>
  HOST_NAME: <your_host_to_deploy>
  THEME_BASE_PATH: web/themes/<base_path>
  THEME_CSS_PATH: web/themes/<path>/css
  PHP_VERSION: '8.3'
  PHP_MAJOR_VERSION: 8
  PHP_MINOR_VERSION: 3

include:
  - project: 'gitlab-ci-cd/drupal'
    ref: main
    file: '/lakedrops.yml'

The tasks for downloading the database dump and to deploy the site finally, depend on your hosting environment and have not been generalized, unless you're using our Ansible environment too, then please refer to Using Ansible to Dump DB and Using Ansible for Deployment below. Otherwise, you have to write the scripts for those two tasks yourselves.

Variables

• COMPOSE_PROJECT_NAME: a string only unique project name which will be used to identify caches and Docker containers.
• HOST_NAME: the host name where you want to deploy your Drupal site
• ENVIRONMENT_NAME: the environment name for the GitLab UI.
• ENVIRONMENT_URL: the environment url of your website
• THEME_BASE_PATH: the relative patch to the base theme, if you want to use one
• THEME_CSS_PATH: the relative path to the theme's css path where the generated artefact can be found.
• PHP_VERSION: '8.3': the string representation of the PHP version
• PHP_MAJOR_VERSION: the major PHP version, defaults to 8.
• PHP_MINOR_VERSION: the minor PHP version, default to 3.
• COMPOSER_DOWNGRADE: by default, composer 2 is being used. To use composer 1 instead, set this variable to 1.
• INITIAL_INSTALL: if set to yes, the initial Drupal site installation gets triggered and all DB and test tasks will be skipped. Can also be used as [INITIAL_INSTALL] in the Git commit message.
• PULL_DB: if set to yes, the download of a fresh database dump will be forced, regardless of any other conditions. Can also be used as [PULL_DB] in the Git commit message.
• DISABLE_CI_TESTS: if this variable is set to any value, the tasks in the test stage will be skipped. This is useful e.g. in a development environment where you push and run pipelines often but don't want to run the tests every single time.
• $DISABLE_GITLAB_CI_TESTS: if this variable is set to "1", no GitLab Tests will be executed, see: GitLab Templates.
• DISABLE_CI_TEST_BACKSTOP: if this variable is set to any value, the visual regression tests with Backstop will be skipped.
• DISABLE_CI_TEST_BEHAT: if this variable is set to any value, the Behat tests will be skipped.
• DISABLE_CI_TEST_CODESTYLE: if this variable is set to any value, the PHP CS tests will be skipped.
• DISABLE_CI_TEST_CYPRESSE2E:: if this variable is set to any value, the Cypress tests will be skipped.
• DISABLE_CI_TEST_PHPUNIT: if this variable is set to any value, the PHP unit tests will be skipped.
• CAE: This variable is being used by the Drupal module Config auto export
• RESET_LOCALE: if set to yes, the interface translations will be wiped completely and built from scratch. Can also be used as [RESET_LOCALE] in the Git commit message.

Usage

This chapter is incomplete so far and needs more attention.

Initial installation of a Drupal site

This pipeline covers both, the initial installation and later updates of a Drupal site. The latter is the default, because it happens regularly whereas the initial installation only happens once.

Therefore, if you run the pipeline the first time to initially install the Drupal site, either add [INITIAL_INSTALL] to your commit message or define the variable INITIAL_INSTALL with the value yes when triggering the pipeline from the GitLab UI.

When either of these conditions apply, no database will be downloaded, imported or updated and all tests will be skipped.

Handling of the database

To build and test your Drupal site prior to deployment, a database with content for this project is required and this is handled by the pipeline pretty smart.

First, it needs to be decided, if a fresh dump of the database needs to be collected or if the already existing database from the previous pipeline run can be re-used. Here is how the prepared pipelines make that decision:

A fresh database is being pulled if one of the following conditions apply, tested in the given order:

• if the pipeline run for the master branch
• if the commit message contains the string [PULL_DB]
• if the variable PULL_DB is set to yes
• if no database container from a previous pipeline exists
• if the database from the previous pipeline doesn't contain any user data yet

If a new database is required, the task Download DB in the build stage will create a dump and make it available as an artifact for subsequent tasks. The task Import DB will then import that dump in the prepare stage.

Otherwise, those two tasks will be skipped and the task Update DB will be executed in the prepare stage instead.

Example

We provide a Demo Drupal 10 project which uses this GitLab CI framework. If you want to give it a try, login to our GitLab, go to the project and click on "Request access". Once we've accepted your request, you can clone the project, make some changes and push them back to the project. This will trigger the pipeline then you can watch running.

The deployed demo site is available online.

The setup for this project is very simple. Because we wanted to protect the pipeline configuration, we removed the default .gitlab-ci.yml file from the repository and configured the usage of the example pipeline configuration that you can review in the Drupal GitLab CI Project.

Also, all the variables have been configured in the GitLab project settings, because developers should not have access to them:

GitLab CI for a single Drupal module

For building and testing a single Drupal.org, custom or contrib module, we make use of the official Drupal project GitLab Templates. To include the templates, we provide a GitLab CI file private-modules, which can be included in your own gitlab-ci.yml file. This includes the following stages:

• build
• validate
• test

To get a complete documentation for this powerful project, see here.

This file private-modules.yml includes another CI template called composer-packages.yml. Here you can store your module as a composer package in your own GitLab installation. The versioning is also included. Now you can use it in a composer.json file. You have to define the repository like this:

"<your-name>": {
      "type": "composer",
      "url": "https://<your-domain>/api/v4/group/<your-group>/-/packages/composer/"
    },