Skip to content

CI/CD Pipeline

Reference for the GitLab CI/CD pipeline configuration of the Image Link Formatter module.

GitLab CI/CD Pipeline Configuration

The CI/CD pipeline is defined in .gitlab-ci.yml and relies on Drupal's shared gitlab_templates.

include block — Drupal shared templates

include:
  - project: $_GITLAB_TEMPLATES_REPO
    ref: $_GITLAB_TEMPLATES_REF
    file:
      - "/includes/include.drupalci.main.yml"
      - "/includes/include.drupalci.variables.yml"
      - "/includes/include.drupalci.workflows.yml"
  - template: Security/SAST.gitlab-ci.yml

The three Drupal template files provide the bulk of the pipeline logic centrally maintained by the Drupal Association:

  • include.drupalci.main.yml — Defines all the actual CI jobs: phpcs, phpstan, eslint, cspell, PHPUnit test jobs, pages, etc.
  • include.drupalci.variables.yml — Declares all opt-in/opt-out variables with their default values and documentation comments.
  • include.drupalci.workflows.yml — Controls when pipelines run (merge requests, pushes to default branch, scheduled runs, etc.).
  • Security/SAST.gitlab-ci.yml — GitLab's built-in static analysis security template, provides semgrep-sast and gitlab-advanced-sast jobs.

Because the templates are pinned via $_GITLAB_TEMPLATES_REF, the pipeline stays aligned with Drupal's ecosystem without requiring manual updates here.

variables block — Opt-in test coverage

variables:
  OPT_IN_TEST_PREVIOUS_MAJOR: 1
  OPT_IN_TEST_PREVIOUS_MINOR: 1
  OPT_IN_TEST_NEXT_MINOR: 1
  OPT_IN_TEST_NEXT_MAJOR: 1
  OPT_IN_TEST_MAX_PHP: 1
  _PHPUNIT_CONCURRENT: 1
  RUN_JOB_UPGRADE_STATUS: 1
  _PHPSTAN_LEVEL: 9

These variables broaden test coverage beyond the Drupal template defaults:

Variable Purpose
OPT_IN_TEST_PREVIOUS_MAJOR Run tests against the previous Drupal major (e.g. D10 when D11 is current)
OPT_IN_TEST_PREVIOUS_MINOR Run tests against the previous Drupal minor release
OPT_IN_TEST_NEXT_MINOR Run tests against the next Drupal minor release
OPT_IN_TEST_NEXT_MAJOR Run tests against the next Drupal major (D12 while on D11)
OPT_IN_TEST_MAX_PHP Run tests against the highest supported PHP version
_PHPUNIT_CONCURRENT Run PHPUnit test groups in parallel to speed up the pipeline
RUN_JOB_UPGRADE_STATUS Enable the upgrade-status compatibility check job
_PHPSTAN_LEVEL PHPStan analysis level — set to 9 (maximum strictness)

Quality gate jobs — allow_failure: false

cspell:
  allow_failure: false
eslint:
  allow_failure: false
phpcs:
  allow_failure: false
phpstan:
  allow_failure: false

By default, the Drupal templates set these jobs to allow_failure: true (they report but don't block merges). This module overrides them to required, meaning a merge request cannot pass CI if any of these checks fail.

cspell — Spell checking and word exclusions

The cspell job checks all source and documentation files for spelling errors. Technical terms, tool names, and project-specific identifiers that are not in the standard dictionary are excluded via a dedicated word list file:

.cspell-project-words.txt — one word per line, with comment sections for organization:

# Tool and library names used in documentation and CI configuration.
doctum
ergebnis
semgrep

# Drupal.org infrastructure and platform identifiers.
drupalcode

When to update this file: Add a new entry whenever cspell fails on a word that is a legitimate technical term (tool name, library, identifier, username) rather than a real spelling mistake. Group related words with a comment for clarity.

Tip

Prefer adding words to .cspell-project-words.txt over the older _CSPELL_WORDS inline variable approach — the file is version-controlled, easier to review in merge requests, and keeps .gitlab-ci.yml clean.

phpstan (previous major) — Attribute stripping for Drupal 10

phpstan (previous major):
  before_script:
    - if [[ "$DRUPAL_CORE" =~ ^10 ]]; then
    -   sed -i '/#\[Group/d' ...
    -   sed -i '/#\[IgnoreDeprecations/d' ...
    -   sed -i '/#\[RunTestsInSeparateProcesses/d' ...
    - fi

PHP attributes like #[Group], #[IgnoreDeprecations], and #[RunTestsInSeparateProcesses] were introduced in later PHPUnit/Drupal versions and are not recognized by Drupal 10. This before_script strips those attribute lines from test files before PHPStan analyses them when running against Drupal 10, preventing false-positive parse errors.

Security scanning — gitlab-advanced-sast and semgrep-sast

gitlab-advanced-sast:
  variables:
    SAST_EXCLUDED_PATHS: "spec, test, tmp, vendor, web"

semgrep-sast:
  variables:
    SAST_EXCLUDED_PATHS: "spec, test, tmp, vendor, web"

Both jobs restrict scanning to the module source only. The vendor/ and web/ directories are installed by the CI environment for test purposes and should not be scanned.

pages job — MkDocs documentation deployment

pages:
  before_script:
    - pip install mkdocs-awesome-pages-plugin

A minimal override of the Drupal-template-provided pages job. It installs one additional plugin before the template's standard MkDocs build runs. The template handles everything else: installing MkDocs + Material theme, running mkdocs build --strict, and deploying the public/ artifact to GitLab Pages.

Supporting Three Drupal Major Versions

This module currently supports Drupal 10, 11, and 12. Maintaining compatibility across three major versions adds complexity in several areas:

  • PHP attributes: Newer PHPUnit attributes (#[Group], #[IgnoreDeprecations], #[RunTestsInSeparateProcesses]) do not exist in Drupal 10's PHPUnit version. The phpstan (previous major) job strips them before analysis (see above).
  • PHPStan level 9: At the maximum strictness level, even minor API changes between Drupal versions can trigger new errors. Watch CI on every Drupal release.
  • Deprecated APIs: Methods or classes deprecated in D10 may be removed in D12. Run the upgrade_status job output regularly to identify upcoming breakages early.
  • Test compatibility: The #[IgnoreDeprecations] attribute suppresses PHPUnit deprecation warnings for tests intentionally testing deprecated paths. When the deprecated code is removed from core, those attributes (and the tests themselves) need to be updated.

#[IgnoreDeprecations] in Test Files

PHPUnit emits deprecation notices whenever tested code calls Drupal APIs marked as deprecated. In cross-version support scenarios, a test may legitimately exercise a code path that is deprecated in the current Drupal version but not yet removed.

The #[IgnoreDeprecations] attribute tells PHPUnit to suppress those warnings for that specific test class, keeping the test output clean without hiding real failures.

#[IgnoreDeprecations]
class ImageLinkFormatterTest extends BrowserTestBase {
  // Test exercises APIs deprecated in D11 but still present
}

Review these periodically

When Drupal removes a deprecated API, tests using #[IgnoreDeprecations] to silence warnings about that API will likely start failing. Review all usages after each Drupal major release.

Pipeline Schedules

Scheduled pipelines run automatically on a cron schedule, independent of code pushes. View and manage them at: pipeline schedules

All schedule jobs are configured with autorun enabled, meaning they trigger automatically without any manual intervention. Typical use cases:

  • Nightly/weekly full test matrix — catches regressions introduced by upstream Drupal core, PHP, or dependency updates even when no code was pushed to the module.
  • Next-major compatibility checks — regularly verifies the module still works against the upcoming Drupal major version, giving early warning of breaking API changes.

When adding a new schedule, ensure the Active toggle is on and the Run pipeline option is set to the correct target branch.

Maintainer Guide: Overview  ·  Getting Started  ·  CI/CD Pipeline  ·  Documentation & Tooling