GitLab CI
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-qualityread the token from theSONAR_TOKENCI variable. Make it masked. Do not pass the token on the command line or in an address.festi-qualitynever prints it. - Do not set
sonar.qualitygate.wait=true. With it, the scanner fails the job on a red gate beforefesti-qualityprints why. festi-qualitywaits at mostsonar.qualitygate.timeoutseconds (300 by default) for the server.festi-qualitysends the token only to anhttpsaddress when the address comes fromreport-task.txtorsonar.host.url, and it follows no redirect. SetSONAR_HOST_URLto the address of the server.- In CI (
CI=true), withoutreport-task.txt,festi-quality --only=sonarfails (exit code2). It does not report an older analysis.