Skip to content
DashboardWebsite

GitLab CI Pack

URL slug: gitlab-ci

The GitLab CI pack turns a unified git diff into analysis units for changed jobs and global sections. It gives the reviewer one job or section at a time, including unchanged context from the same hunk.

The pack claims these pipeline files with file_globs:

GlobMatches
.gitlab-ci.ymlThe root pipeline
*.gitlab-ci.ymlFiles with this name pattern in any folder, such as ci/deploy.gitlab-ci.yml
.gitlab/ci/*.ymlYAML files in .gitlab/ci/

A pipeline file under another name, such as ci/build.yml, can reach the pack through sniff(). When no glob claims a diff file, core scores its added lines with packs that recognise content (OpenTremor-core#0035). This pack returns 0.8 when the content matches GitLab CI’s schema and 0.0 otherwise:

  • A top-level stages: with plain stage names, such as - build or [build, test].
  • A top-level key with a script: key directly under it.

Other YAML formats can also contain stages: or script:, so the pack checks their structure. Azure Pipelines uses mappings such as - stage: Build. Ansible tasks are list items, not top-level keys.

parse_diff (opentremor_pack_gitlab_ci/parser.py) processes each hunk:

  1. Core’s iter_hunks reads the diff (opentremor_core.libs.diff). The parser handles every .yml or .yaml file in the diff, including files routed by content.
  2. Core’s iter_yaml_blocks locates changed YAML blocks and their key paths (opentremor_core.libs.yaml_diff). The first path segment is the top-level key.
  3. The parser groups changed blocks by top-level key. Changes in the same job form one unit.
  4. The parser widens each unit to include the key’s context in the hunk, up to the next top-level key. A change to script: can include unchanged environment: and rules: lines when they appear in the hunk.

When a hunk starts inside a job, Git’s hunk heading can supply the job name, for example @@ -20,4 +20,5 @@ deploy-production:. Git omits keys that start with a dot from the heading. A hunk inside a hidden job such as .deploy-template: can therefore have the name unknown.

Top-level keytypename
include, default, variables, workflow, stages, specThe keywordThe keyword
image, services, cache, before_script, after_script (deprecated globals)The keywordThe keyword
Any other keyjobThe job name
A hunk inside a job whose name is unavailablejobunknown
A changed top-level comment on its ownfile(top level)

metadata.source_path is the file path from the diff header.

The pack has one implicit ruleset, rules/gitlab-ci-rules.md; list_rule_types() is empty. Rules that depend on runner configuration or project settings are review prompts. They use LOW confidence and no more than MEDIUM severity, and tell the reviewer what to check.

RuleSeverity/ConfidenceWhat it catches
GLCI-001HIGH/HIGHAn external project include without a pinned ref, a component without a pinned version, or a remote URL
GLCI-002MEDIUM/MEDIUMAn image: or services: entry with a mutable tag and no digest, outside approved registries
GLCI-003HIGH/MEDIUMA job that adds a docker:dind service or sets DOCKER_HOST to a Docker-in-Docker daemon. Check runner isolation
GLCI-004HIGH/MEDIUMA deploy job whose rules: or only: now allow it to run for merge requests, forks, or unprotected branches
GLCI-005MEDIUM/LOWwhen: manual removed from a production deploy
GLCI-006HIGH/MEDIUMA security scan weakened by removing a security template include, allowing a scan job to fail, or disabling a scan
GLCI-007HIGH/MEDIUMA secret exposed in the job log through debug tracing, set -x, or output that masking misses
GLCI-008HIGH/MEDIUMUnquoted merge request or branch metadata in a shell command
GLCI-009HIGH/MEDIUMA download executed without an integrity check
GLCI-010HIGH/HIGHartifacts: that publish .env files, keys, or credential files
GLCI-011MEDIUM/LOWCI_JOB_TOKEN used to push or call another project. Check the token allowlist

Performance findings have LOW or MEDIUM severity. They appear in the review and do not fail the merge check on their own.

RuleSeverity/ConfidenceWhat it catches
GLCI-PERF-001LOW/MEDIUMA merge request job without interruptible: true
GLCI-PERF-002MEDIUM/MEDIUMworkflow: rules: that create both a branch pipeline and a merge request pipeline for one push
GLCI-PERF-003LOW/HIGHA cache key that changes on every run, such as one using $CI_PIPELINE_ID or $CI_JOB_ID
GLCI-PERF-004LOW/LOWA new job with no needs:
GLCI-PERF-005LOW/MEDIUMparallel: or parallel: matrix: increased, with the number of jobs added
GLCI-PERF-006LOW/LOWartifacts: with no expire_in
GLCI-PERF-007LOW/LOWGIT_DEPTH: 0 or GIT_STRATEGY: clone added when no step needs the full history or tags

Reliability findings have LOW or MEDIUM severity. They appear in the review and do not fail the merge check on their own.

RuleSeverity/ConfidenceWhat it catches
GLCI-REL-001MEDIUM/LOWA deploy job with no resource_group. Check that deploys cannot overlap
GLCI-REL-002MEDIUM/MEDIUMallow_failure: true added to a test or deploy job
GLCI-REL-003LOW/MEDIUMretry: set to max: 2 without a when: filter

Built-in rules seed an organization’s custom_rules as editable rows. An organization can reword, disable, or replace them without changing this package. Core keeps rows that an organization has not edited in step with this file (OpenTremor-core#0034). GLCI-002 includes a default list of approved registries; replace it with the organization’s own list.

The pack includes a sample merge request that changes a deploy template include from a tag to main, adds a remote include, publishes .env as a build artifact, and lets a production deploy run in merge request pipelines without manual approval.

  • Runner configuration. Privileged mode, executor isolation, and tags are set on the runner. GLCI-003 asks the reviewer to check runner isolation.
  • Project settings. Protected branches, protected environments, the job token allowlist, and auto-cancel are configured in GitLab settings. Rules that depend on these settings are review prompts.
  • Included content. The pack reviews the include: line, not the file it pulls in. A file included in the same diff is reviewed as its own file.