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.
Routing
Section titled “Routing”The pack claims these pipeline files with file_globs:
| Glob | Matches |
|---|---|
.gitlab-ci.yml | The root pipeline |
*.gitlab-ci.yml | Files with this name pattern in any folder, such as ci/deploy.gitlab-ci.yml |
.gitlab/ci/*.yml | YAML 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- buildor[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.
How the pack parses diffs
Section titled “How the pack parses diffs”parse_diff (opentremor_pack_gitlab_ci/parser.py) processes each hunk:
- Core’s
iter_hunksreads the diff (opentremor_core.libs.diff). The parser handles every.ymlor.yamlfile in the diff, including files routed by content. - Core’s
iter_yaml_blockslocates changed YAML blocks and their key paths (opentremor_core.libs.yaml_diff). The first path segment is the top-level key. - The parser groups changed blocks by top-level key. Changes in the same job form one unit.
- 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 unchangedenvironment:andrules: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.
How the pack identifies units
Section titled “How the pack identifies units”| Top-level key | type | name |
|---|---|---|
include, default, variables, workflow, stages, spec | The keyword | The keyword |
image, services, cache, before_script, after_script (deprecated globals) | The keyword | The keyword |
| Any other key | job | The job name |
| A hunk inside a job whose name is unavailable | job | unknown |
| A changed top-level comment on its own | file | (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.
Security
Section titled “Security”| Rule | Severity/Confidence | What it catches |
|---|---|---|
GLCI-001 | HIGH/HIGH | An external project include without a pinned ref, a component without a pinned version, or a remote URL |
GLCI-002 | MEDIUM/MEDIUM | An image: or services: entry with a mutable tag and no digest, outside approved registries |
GLCI-003 | HIGH/MEDIUM | A job that adds a docker:dind service or sets DOCKER_HOST to a Docker-in-Docker daemon. Check runner isolation |
GLCI-004 | HIGH/MEDIUM | A deploy job whose rules: or only: now allow it to run for merge requests, forks, or unprotected branches |
GLCI-005 | MEDIUM/LOW | when: manual removed from a production deploy |
GLCI-006 | HIGH/MEDIUM | A security scan weakened by removing a security template include, allowing a scan job to fail, or disabling a scan |
GLCI-007 | HIGH/MEDIUM | A secret exposed in the job log through debug tracing, set -x, or output that masking misses |
GLCI-008 | HIGH/MEDIUM | Unquoted merge request or branch metadata in a shell command |
GLCI-009 | HIGH/MEDIUM | A download executed without an integrity check |
GLCI-010 | HIGH/HIGH | artifacts: that publish .env files, keys, or credential files |
GLCI-011 | MEDIUM/LOW | CI_JOB_TOKEN used to push or call another project. Check the token allowlist |
Performance
Section titled “Performance”Performance findings have LOW or MEDIUM severity. They appear in the review and do not fail the merge check on their own.
| Rule | Severity/Confidence | What it catches |
|---|---|---|
GLCI-PERF-001 | LOW/MEDIUM | A merge request job without interruptible: true |
GLCI-PERF-002 | MEDIUM/MEDIUM | workflow: rules: that create both a branch pipeline and a merge request pipeline for one push |
GLCI-PERF-003 | LOW/HIGH | A cache key that changes on every run, such as one using $CI_PIPELINE_ID or $CI_JOB_ID |
GLCI-PERF-004 | LOW/LOW | A new job with no needs: |
GLCI-PERF-005 | LOW/MEDIUM | parallel: or parallel: matrix: increased, with the number of jobs added |
GLCI-PERF-006 | LOW/LOW | artifacts: with no expire_in |
GLCI-PERF-007 | LOW/LOW | GIT_DEPTH: 0 or GIT_STRATEGY: clone added when no step needs the full history or tags |
Reliability
Section titled “Reliability”Reliability findings have LOW or MEDIUM severity. They appear in the review and do not fail the merge check on their own.
| Rule | Severity/Confidence | What it catches |
|---|---|---|
GLCI-REL-001 | MEDIUM/LOW | A deploy job with no resource_group. Check that deploys cannot overlap |
GLCI-REL-002 | MEDIUM/MEDIUM | allow_failure: true added to a test or deploy job |
GLCI-REL-003 | LOW/MEDIUM | retry: 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.
What the pack does not cover
Section titled “What the pack does not cover”- Runner configuration. Privileged mode, executor isolation, and tags are set on the runner.
GLCI-003asks 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.