CI configuration check
The CI configuration check reads the CI configuration a merge request adds or changes, before it runs. CI jobs run with the project's secrets, tokens and deploy access, so a change to the CI configuration can hand them to someone else, or make the pipeline run code nobody reviewed. The check looks for the patterns that most often lead to a stolen token or a hijacked build:
- GitHub: GitHub Actions workflows: untrusted input expanded into scripts, a privileged workflow checking out the pull request's code, actions not pinned to a commit, and
write-allpermissions. - GitLab: GitLab CI configuration: remote includes without an integrity hash; includes, components and images not pinned; debug logging turned on; caches shared with unprotected branches; merge request text run as shell code; and pushed branch or tag names choosing what is included or run.
Each finding has a file, a line, a rule and a severity (high, medium or low). In the policy it is the CI configuration row of the Checks tab (API: controls.workflows).
What it checks
Which files: GitHub
- Files directly in
.github/workflows/ending in.ymlor.yaml. Files in sub-folders of.github/workflows/, composite actions and other YAML files are not checked. - Only files the pull request adds or changes. Deleted workflows are not checked.
Which files: GitLab
- The project's CI configuration file, when the merge request changes it. Merge Pilot reads the project's CI/CD configuration file setting from GitLab: when it is empty, the file is
.gitlab-ci.yml; when it is a path in the repository (such asci/pipeline.yml), that file. - YAML files under
.gitlab/ci/(.ymlor.yaml, any depth) that the merge request adds or changes. - Changed files the configuration file includes with
include:local, or with the short form (a plain path such asinclude: 'ci/build.yml'; anhttp://orhttps://address is a remote include). Wildcards work as in GitLab:*stays in one folder (configs/*.yml),configs/**.ymlmatchesconfigsand every sub-folder,configs/**/*.ymlonly the sub-folders. Only.ymland.yamlfiles are included, as in GitLab. A changed included file is checked even when the configuration file itself did not change; the configuration file is read at the head commit to find its includes. - Includes are followed one level: what an included file includes in turn is not followed. At most 50
include:localentries are followed; a configuration file with more makes the check fail. An include path built from a CI/CD variable is not followed, since its value is only known when the pipeline runs. - Includes from another project, from a remote address or of a component are not read: they are checked for pinning only (see the rules below). GitLab templates are not read. Includes with
rules:count as always included, since GitLab decides them only when the pipeline runs. - When the project's CI/CD configuration file is outside the repository (an address, or a file in another project,
path@group/project), nothing is checked. The check passes with the note The project's CI/CD configuration is outside the repository (…), so it was not checked. - Deleted files are not checked.
On both
- Each file is read as it is at the merge request's head commit.
- At most 50 CI configuration files are checked per merge request. When more are changed, the check fails (it does not pass files it did not read).
- When the VCS lists only part of the merge request's changed files, the check fails: a changed CI file may have been missed.
These two follow the company's When a scan cannot see everything (see Scanning); a policy can set its own. With Check the first ones up to the limit or Check what was listed, the check looks at those and names what it did not look at in the control's reason (Not looked at: …). A check failed this way is not retried by itself.
Rules on GitHub
| Rule | Severity | What is found | Why it matters | What to do |
|---|---|---|---|---|
script-injection | High | A run: step, or the script: input of actions/github-script, expands an untrusted value inside ${{ }}: github.head_ref, or a github.event property whose last part is body, default_branch, email, head_ref, label, message, name, page_name, ref or title (for example github.event.pull_request.title) | Whoever opens the pull request or issue writes these values. Pasted into a script, a crafted title runs as commands, with the workflow's secrets and token | Pass the value through an environment variable instead |
untrusted-checkout | High | A workflow triggered by pull_request_target or workflow_run uses actions/checkout with a ref: that names the pull request's code: github.event.pull_request.head…, github.head_ref, github.event.workflow_run.head… or refs/pull/… | These triggers run with the repository's secrets and a write token. Checking out the pull request's code there lets that code use them | Do not check out and run the pull request's code in a privileged workflow |
unpinned-action | Medium | A uses: reference, in a step or a job (reusable workflows), names a tag or branch instead of a full 40-character commit SHA | The action's owner, or whoever takes over the action, can move a tag or branch to other code; a commit SHA cannot be moved | Pin it to a full commit SHA, or allow its owner (below) |
write-all | Medium | permissions: write-all, for the whole workflow or for one job | It runs nothing by itself, but it widens what any other flaw can do | Grant only the scopes the jobs need |
syntax | Low | The file is not valid YAML, or is not a workflow (not a mapping) | GitHub does not run a file it cannot read, so nothing runs; the finding says the file was not checked | Fix the file |
Rules on GitLab
| Rule | Severity | What is found | Why it matters | What to do |
|---|---|---|---|---|
script-injection | High | In script, before_script or after_script, a predefined variable whose value whoever pushes or opens the merge request writes is placed in the command string of eval, sh -c or bash -c. The variables are CI_MERGE_REQUEST_TITLE, CI_MERGE_REQUEST_DESCRIPTION, CI_MERGE_REQUEST_SOURCE_BRANCH_NAME, CI_EXTERNAL_PULL_REQUEST_SOURCE_BRANCH_NAME, CI_COMMIT_MESSAGE, CI_COMMIT_TITLE, CI_COMMIT_DESCRIPTION, CI_COMMIT_AUTHOR, CI_COMMIT_REF_NAME, CI_COMMIT_BRANCH, CI_COMMIT_TAG, CI_COMMIT_TAG_MESSAGE and GITLAB_USER_NAME | The job's shell substitutes a variable's value; that alone does not run it. Handing the value to eval or sh -c runs it again as shell code, so a crafted merge request title or commit message runs commands with the job's variables and token. A variable in single quotes reaches the inner shell unexpanded and is not flagged | Use the variable directly ("$CI_MERGE_REQUEST_TITLE"), not through eval or sh -c |
debug-trace | High | CI_DEBUG_TRACE or CI_DEBUG_SERVICES set to true in a variables: section, at the top level or in a job | GitLab's own documentation calls debug logging a serious security risk | Do not commit it |
include-remote | High | include:remote, or an include given as an http:// or https:// address, without integrity: | The jobs come from an address outside GitLab's access control and can change between runs. GitLab advises saving the file in the repository instead | Save the file in the repository, or add integrity: with the file's SHA256 hash (GitLab 17.9 and later) |
include-project-unpinned | Medium | include:project without ref:, or with a ref: that is not a full 40-character commit SHA | Without ref, GitLab takes the file from that project's HEAD at every run. A branch or tag can be moved to other content; GitLab recommends the full commit SHA as the most stable choice | Pin it with ref: <full commit SHA>, or allow the project (below) |
component-unpinned | Medium | include:component with no version, with ~latest, or with a version that is not a commit SHA (a tag or a partial version) | ~latest takes the newest release at every run, and a tag can be moved; a commit SHA cannot | Pin it to a commit SHA (component@<sha>), or allow the component (below) |
image-unpinned | Medium | An image or a services entry (a string, or name: in the long form), at the top level, in default: or in a job, without an @sha256: digest, or built from a CI/CD variable | A new push of the same tag changes what runs. GitLab advises digests for images, and avoiding variables in image names because they can be changed to point to a malicious image | Name the image with @sha256:<digest>, or allow its prefix (below) |
cache-unprotect | Medium | cache:unprotect: true | The cache is then shared between protected and unprotected branches: someone who may push only to unprotected branches can read and write the cache that protected pipelines use | Remove it |
variable-chooses-source | Medium | $CI_COMMIT_REF_NAME in an include's local, remote, project, ref or file; or one of the variables listed under script-injection in an image, a services name or trigger:project | GitLab substitutes these values itself. That runs nothing, but the branch or tag name, or the merge request text, then chooses which file is included, which image runs or which project's pipeline starts | Use a fixed value |
syntax | Low | The file is not valid YAML, or is not a GitLab CI configuration (not a mapping) | GitLab does not run a file it cannot read; the finding says the file was not checked | Fix the file |
An anchor used twice (<<: *defaults) is reported once, at the anchor.
Allow-lists
| Allow-list (label in the UI) | VCS | Entries | What it allows | Default |
|---|---|---|---|---|
| Actions that need not be pinned | GitHub | owner/* (every repository of that owner) or owner/repo; * is a wildcard and matching ignores case. Each entry must have exactly one /; anything else is refused when it is saved | Their actions may use a tag or branch | actions/*, github/* (GitHub's own actions). An empty list requires every action to be pinned |
| GitLab includes that need not be pinned | GitLab | Project paths (group/project) or component paths without a version (gitlab.com/components/sast); * wildcards. An entry needs at least one / and no spaces or @ | Their include:project refs and component versions need not be a commit SHA | None: every include must be pinned |
| Images allowed without a digest | GitLab | Image name prefixes (registry.example.com/ci/), no spaces | Images and services whose name starts with the prefix need no digest | None: every image needs one |
A GitHub uses: reference also passes the pinning rule when it is a local action or workflow (./…), a Docker image (docker://…), contains an expression (${{ … }}) or names no version (no @).
Modes
The control's mode is set in the policy editor, Checks tab, row CI configuration.
| Mode (label in the UI) | API value | What it does |
|---|---|---|
| Off | off | The check does not run. This is the default of a new policy |
| Report | report | The check runs and its result is shown on the merge request; it never holds the merge |
| Enforce | block | The merge gate waits while the check runs, and is blocked while the check has findings (at or above Hold for) or could not be completed |
Hold for (minimum severity)
In Enforce mode, Hold for chooses which findings hold the merge: Every finding (the default), Medium and above or High and above (API controls.workflows.min_severity: absent, medium or high; the API also takes low, the same as every finding). Findings below it are still shown on the merge request and in the comment; they do not hold the merge.
What the control says
| Result | Shown as | In Enforce mode | In Report mode |
|---|---|---|---|
| The check is running (or has not run yet) for the head commit | Checking the changed CI configuration. | The gate waits | Shown, does not hold |
| No findings | No problems in the changed CI configuration. | Passes | Passes |
| Findings, all below Hold for | No problems of high severity or higher in the changed CI configuration; N lower-severity finding(s) reported. | Passes | Passes |
| Findings | N problem(s) in the changed CI configuration. | The gate is blocked | Shown as a warning |
| The check could not be completed | The CI configuration check could not be completed: … | The gate is blocked | Shown as a warning |
| A watched repository whose company runs no scans on watched merge requests | Not scanned: scans are off for watched repositories. | Skipped | Skipped |
When a GitLab project's CI configuration is outside the repository, the passing message ends with that note.
See Controls for how modes combine into the merge gate.
Settings
In the policy
Shown when the mode is Report or Enforce (Hold for only in Enforce). Each allow-list offers Company setting (…), which uses the company's list shown in brackets, or This policy's list, which replaces it for this policy with the list typed below it (an empty list of the policy's own is a real choice).
| Setting (label in the UI) | What it does | Default | Allowed values | Set where | Who can change it | API field |
|---|---|---|---|---|---|---|
| CI configuration | The control's mode | Off | Off, Report, Enforce | Policy | Policy managers, company admins, platform admins | controls.workflows.mode (off, report, block) |
| Hold for | Which findings hold the merge in Enforce mode | Every finding | Every finding, Medium and above, High and above | Policy | Same | controls.workflows.min_severity |
| Actions that need not be pinned | See Allow-lists | Company setting | owner/* or owner/repo, separated by commas | Policy override | Same | controls.workflows.overrides.pin_allowed (absent or null: the company's list) |
| GitLab includes that need not be pinned | See Allow-lists | Company setting | Project or component paths without a version, separated by commas | Policy override | Same | controls.workflows.overrides.include_allowed |
| Images allowed without a digest | See Allow-lists | Company setting | Image name prefixes, separated by commas | Policy override | Same | controls.workflows.overrides.image_allowed |
Company default
The company's lists are on the company page, Scanning tab, section CI configuration, card CI configuration.
| Setting (label in the UI) | Default | Allowed values | Who can change it | API field |
|---|---|---|---|---|
| Actions that need not be pinned | actions/*, github/* | owner/* or owner/repo, one per line; empty: every action must be pinned | Company admins, platform admins | scanning.workflows.pin_allowed (absent or null: the default list; []: none) |
| GitLab includes that need not be pinned | Empty | Project paths or component paths without a version, one per line, * wildcards | Same | scanning.workflows.include_allowed |
| Images allowed without a digest | Empty | Image name prefixes, one per line | Same | scanning.workflows.image_allowed |
The company settings are saved with Save changes on the company page (PUT /api/v1/companies/{id} with the scanning object).
When it runs
- When a merge request is opened or gets a new head commit, and the policy covering it has the control in Report or Enforce, Merge Pilot queues a
workflow_scanjob (see Jobs), on GitHub and on GitLab. The merge request is evaluated again when the job ends. - It runs once per head commit. A new commit starts it again.
- Re-scan on the merge request's CI configuration check card starts it again for the current head (
POST /api/v1/merge-requests/{id}/rescanwith{"scan": "workflow"}). It is refused when the merge request's policy does not run the check (the merge request's policy does not run the CI configuration check). Auditors cannot re-scan. See Re-running checks. - When the check cannot finish (the VCS did not answer, a file could not be read, a limit was reached): the check fails, never passes. What happens next follows An image, infrastructure or CI configuration scan could not complete under When a scan cannot see everything (the company's, or the policy's own): wait for a re-scan (the default; in the policy editor Fail, rescan by hand) or retry after a pause (Fail, retry automatically; 10 minutes unless the installation sets another). A check failed by a limit or a cut-short file list is not retried. See Controls.
- When the VCS's API rate limit is used up, the job waits for the limit to reset; this is not a failure.
- On watched repositories it runs only when the company scans watched merge requests (Company → Repositories, Scan watched merge requests for secrets, vulnerable dependencies and licenses; the CI configuration check counts as a scan).
What the merge request shows
- Policy card: the CI configuration line of the decision checklist, with the result above. In Report mode a failure is marked (report only).
- CI configuration check card: Scan in progress while it runs; Scan failed: … with the error; No problems in N changed CI configuration files.; a note when something was not checked; or each finding with its
file:line, the explanation, its severity and the rule. - My Work: a merge request held by this control is listed with the reason CI configuration check failed.
- A Merge Pilot: CI configuration check comment on the merge request lists the findings in the changed GitHub Actions workflows or the changed GitLab CI configuration in a table (file, line, severity, rule, problem). It is posted when there are findings and updated afterwards, also to say the problems are gone; it is not edited when nothing changed. Nothing is written to a watched repository.
- The merge gate's check and the status comment on the merge request list the control with the other controls.
Exceptions
There is no exception per finding. To accept an action, include or image that is not pinned, add it to the matching allow-list, for the company or for one policy. To let lower-severity findings through, set Hold for. To let a policy show findings without holding the merge, set the control to Report.
Audit log
| Action | When |
|---|---|
workflow_problems_detected | The check found problems in the changed CI configuration (written again when the number of findings changes). Details: the repository, the merge request number, the number of findings and the files checked |
workflow_rescan | Someone started the check again |
job_failed | A workflow_scan job used up all its attempts |
See Audit log.
API fields
| Where | Field | Meaning |
|---|---|---|
| Policy | controls.workflows.mode | off, report or block |
| Policy | controls.workflows.min_severity | low, medium or high; absent: every finding holds |
| Policy | controls.workflows.overrides.pin_allowed, .include_allowed, .image_allowed | The policy's own lists; absent: the company's |
| Company | scanning.workflows.pin_allowed, .include_allowed, .image_allowed | The company's lists |
| Merge request | workflow_scan.status | pending, completed or failed |
| Merge request | workflow_scan.head_sha | The commit that was checked |
| Merge request | workflow_scan.files_scanned | How many CI configuration files were checked |
| Merge request | workflow_scan.findings[] | file, line, rule, severity (high, medium, low), message |
| Merge request | workflow_scan.note | What was not checked and why (a GitLab CI configuration outside the repository) |
| Merge request | workflow_scan.error | Why the check could not be completed |
| Merge request | decision.controls[] with control: "workflows" | The control's status (passed, pending, failed, skipped), blocking and reason |
Related pages
- Controls: every control and how modes work.
- CI: the CI control, which does not count runs of a change that edits its own CI configuration.
- Dependency sources: where the dependencies a change adds come from.
- Scanning: the When a scan cannot see everything settings this check follows.
- Jobs: the
workflow_scanjob.
Video tutorial
Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →