GitLab CI

Back to the README

The package ships the jobs, so a project includes them instead of pasting them:

include:
  - project: 'FestiCore/php_festi_codingstandard'
    ref: '1.3.3'
    file: '/ci/static-analysis.gitlab-ci.yml'

variables:
  FESTI_RUNNER_TAG: "kuber"   # required
Job Blocks a merge request? Runs on Does
festi:phpcs:changed yes merge requests festi-phpcs-diff: errors in the code the branch changed, complexity only where the branch raised it
festi:phpcs:full no the default branch phpcs over the whole tree, to keep the backlog visible
festi:phan yes merge requests and the default branch Phan with the project's .phan/config.php
festi:phpmd no merge requests and the default branch class size and coupling over the whole tree

Four things to get right

Set FESTI_RUNNER_TAG. Every runner on gitlab.varteq.com is tagged. A job whose tag no runner serves is never picked up: it sits pending and fails as stuck_pending_no_matching_runners, which looks like a hung pipeline rather than a failed check. Set the variable once; do not override tags per job.

Name a ref that exists. Tags on this project carry no v prefix (1.3.1, not v1.3.1). An include: with a ref that does not exist fails when the pipeline is created, so no job runs at all.

Give the project read access to FestiCore/php_festi_codingstandard, or the include cannot be fetched.

Use a runner that applies the image. The jobs use the image php:8.5-cli, the PHP of the Festi projects. Only a Docker or Kubernetes executor applies an image, for example the runners with the tag kuber. A shell runner uses its own PHP, so on a shell runner the jobs run on the PHP of that runner. The image has no Composer, git or unzip: the jobs install them when they are missing.

Variables

Variable Default Meaning
FESTI_RUNNER_TAG php8.1 Tag of the runner that takes the jobs.
FESTI_PHPCS_PATHS ./ What phpcs looks at.
FESTI_PHPCS_IGNORE vendor/**,public/**,**/themes/**,.phan/** phpcs ignore patterns.
FESTI_PHPCS_STANDARD Festi Set to phpcs.xml when the project has its own ruleset.
FESTI_PHAN_CONFIG .phan/config.php The project's Phan configuration.
FESTI_PHPMD_PATHS ./ What PHPMD measures. Separate the paths with commas.
FESTI_PHPMD_EXCLUDE vendor/*,tests/* PHPMD exclude patterns. Separate the patterns with commas: the job gives each pattern to PHPMD alone.
FESTI_PHPMD_RULESET the shipped phpmd/ruleset.xml Set to phpmd.xml when the project has its own ruleset.

The jobs set GIT_DEPTH: 0, because the changed-lines job needs the merge base and GitLab clones shallow by default.

Fitting the jobs into a pipeline

The jobs use the test stage. Override it per job when the pipeline has none:

festi:phpcs:changed:
  stage: analysis

To run the whole toolchain as one job instead, call festi-quality yourself. --strict makes it fail on an issue, --only chooses the tools:

quality:changed:
  stage: test
  tags: ["php8.1"]
  variables:
    GIT_DEPTH: 0
  script:
    - composer install --no-interaction --prefer-dist --no-progress
    - vendor/bin/festi-quality --diff --strict --list --only=phpcs,phpmd,phan
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

Note the difference from festi:phpcs:changed: this also gates on PHPMD's class measures and on Phan, and under --strict a warning fails the job too.

SonarQube

The scan is the project's own job. After the scan, the job calls vendor/bin/festi-quality --only=sonar. Do not write a Sonar report parser in the project: this command is the shared one.

The command waits until the server has processed the scan of the job. Then it prints the quality gate with each condition, the open issues, the security hotspots to review and the files with new uncovered lines. A red gate fails the job (exit code 1). See SonarQube in the sonar job for the output.

On a runner that has PHP, Composer and sonar-scanner, one job does both:

sonar:
  stage: test
  variables:
    GIT_DEPTH: 0
  script:
    - composer install --no-interaction --prefer-dist --no-progress
    - sonar-scanner
    - vendor/bin/festi-quality --only=sonar

The image sonarsource/sonar-scanner-cli has no PHP. With that image, the scan job keeps .scannerwork/report-task.txt as an artifact, and a second job on a PHP image reads it:

sonar:scan:
  stage: test
  image:
    name: sonarsource/sonar-scanner-cli:11
    entrypoint: [""]
  variables:
    GIT_DEPTH: 0
  script:
    - sonar-scanner
  artifacts:
    paths:
      - .scannerwork/report-task.txt

sonar:report:
  stage: test
  image: php:8.5-cli
  needs: ["sonar:scan"]
  script:
    - composer install --no-interaction --prefer-dist --no-progress
    - vendor/bin/festi-quality --only=sonar

The PHP image has no Composer, git or unzip: install them as the before_script of the shipped jobs does.

Four things to get right:

  • The scanner and festi-quality read the token from the SONAR_TOKEN CI variable. Make it masked. Do not pass the token on the command line or in an address. festi-quality never prints it.
  • Do not set sonar.qualitygate.wait=true. With it, the scanner fails the job on a red gate before festi-quality prints why.
  • festi-quality waits at most sonar.qualitygate.timeout seconds (300 by default) for the server.
  • festi-quality sends the token only to an https address when the address comes from report-task.txt or sonar.host.url, and it follows no redirect. Set SONAR_HOST_URL to the address of the server.
  • In CI (CI=true), without report-task.txt, festi-quality --only=sonar fails (exit code 2). It does not report an older analysis.