Skip to main content
Video tutorial · 1:15

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-all permissions.
  • 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 .yml or .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 as ci/pipeline.yml), that file.
  • YAML files under .gitlab/ci/ (.yml or .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 as include: 'ci/build.yml'; an http:// or https:// address is a remote include). Wildcards work as in GitLab: * stays in one folder (configs/*.yml), configs/**.yml matches configs and every sub-folder, configs/**/*.yml only the sub-folders. Only .yml and .yaml files 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:local entries 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​

RuleSeverityWhat is foundWhy it mattersWhat to do
script-injectionHighA 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 tokenPass the value through an environment variable instead
untrusted-checkoutHighA 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 themDo not check out and run the pull request's code in a privileged workflow
unpinned-actionMediumA uses: reference, in a step or a job (reusable workflows), names a tag or branch instead of a full 40-character commit SHAThe action's owner, or whoever takes over the action, can move a tag or branch to other code; a commit SHA cannot be movedPin it to a full commit SHA, or allow its owner (below)
write-allMediumpermissions: write-all, for the whole workflow or for one jobIt runs nothing by itself, but it widens what any other flaw can doGrant only the scopes the jobs need
syntaxLowThe 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 checkedFix the file

Rules on GitLab​

RuleSeverityWhat is foundWhy it mattersWhat to do
script-injectionHighIn 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_NAMEThe 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 flaggedUse the variable directly ("$CI_MERGE_REQUEST_TITLE"), not through eval or sh -c
debug-traceHighCI_DEBUG_TRACE or CI_DEBUG_SERVICES set to true in a variables: section, at the top level or in a jobGitLab's own documentation calls debug logging a serious security riskDo not commit it
include-remoteHighinclude: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 insteadSave the file in the repository, or add integrity: with the file's SHA256 hash (GitLab 17.9 and later)
include-project-unpinnedMediuminclude:project without ref:, or with a ref: that is not a full 40-character commit SHAWithout 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 choicePin it with ref: <full commit SHA>, or allow the project (below)
component-unpinnedMediuminclude: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 cannotPin it to a commit SHA (component@<sha>), or allow the component (below)
image-unpinnedMediumAn 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 variableA 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 imageName the image with @sha256:<digest>, or allow its prefix (below)
cache-unprotectMediumcache:unprotect: trueThe 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 useRemove it
variable-chooses-sourceMedium$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:projectGitLab 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 startsUse a fixed value
syntaxLowThe 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 checkedFix the file

An anchor used twice (<<: *defaults) is reported once, at the anchor.

Allow-lists​

Allow-list (label in the UI)VCSEntriesWhat it allowsDefault
Actions that need not be pinnedGitHubowner/* (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 savedTheir actions may use a tag or branchactions/*, github/* (GitHub's own actions). An empty list requires every action to be pinned
GitLab includes that need not be pinnedGitLabProject 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 SHANone: every include must be pinned
Images allowed without a digestGitLabImage name prefixes (registry.example.com/ci/), no spacesImages and services whose name starts with the prefix need no digestNone: 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 valueWhat it does
OffoffThe check does not run. This is the default of a new policy
ReportreportThe check runs and its result is shown on the merge request; it never holds the merge
EnforceblockThe 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​

ResultShown asIn Enforce modeIn Report mode
The check is running (or has not run yet) for the head commitChecking the changed CI configuration.The gate waitsShown, does not hold
No findingsNo problems in the changed CI configuration.PassesPasses
Findings, all below Hold forNo problems of high severity or higher in the changed CI configuration; N lower-severity finding(s) reported.PassesPasses
FindingsN problem(s) in the changed CI configuration.The gate is blockedShown as a warning
The check could not be completedThe CI configuration check could not be completed: …The gate is blockedShown as a warning
A watched repository whose company runs no scans on watched merge requestsNot scanned: scans are off for watched repositories.SkippedSkipped

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 doesDefaultAllowed valuesSet whereWho can change itAPI field
CI configurationThe control's modeOffOff, Report, EnforcePolicyPolicy managers, company admins, platform adminscontrols.workflows.mode (off, report, block)
Hold forWhich findings hold the merge in Enforce modeEvery findingEvery finding, Medium and above, High and abovePolicySamecontrols.workflows.min_severity
Actions that need not be pinnedSee Allow-listsCompany settingowner/* or owner/repo, separated by commasPolicy overrideSamecontrols.workflows.overrides.pin_allowed (absent or null: the company's list)
GitLab includes that need not be pinnedSee Allow-listsCompany settingProject or component paths without a version, separated by commasPolicy overrideSamecontrols.workflows.overrides.include_allowed
Images allowed without a digestSee Allow-listsCompany settingImage name prefixes, separated by commasPolicy overrideSamecontrols.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)DefaultAllowed valuesWho can change itAPI field
Actions that need not be pinnedactions/*, github/*owner/* or owner/repo, one per line; empty: every action must be pinnedCompany admins, platform adminsscanning.workflows.pin_allowed (absent or null: the default list; []: none)
GitLab includes that need not be pinnedEmptyProject paths or component paths without a version, one per line, * wildcardsSamescanning.workflows.include_allowed
Images allowed without a digestEmptyImage name prefixes, one per lineSamescanning.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_scan job (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}/rescan with {"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​

ActionWhen
workflow_problems_detectedThe 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_rescanSomeone started the check again
job_failedA workflow_scan job used up all its attempts

See Audit log.

API fields​

WhereFieldMeaning
Policycontrols.workflows.modeoff, report or block
Policycontrols.workflows.min_severitylow, medium or high; absent: every finding holds
Policycontrols.workflows.overrides.pin_allowed, .include_allowed, .image_allowedThe policy's own lists; absent: the company's
Companyscanning.workflows.pin_allowed, .include_allowed, .image_allowedThe company's lists
Merge requestworkflow_scan.statuspending, completed or failed
Merge requestworkflow_scan.head_shaThe commit that was checked
Merge requestworkflow_scan.files_scannedHow many CI configuration files were checked
Merge requestworkflow_scan.findings[]file, line, rule, severity (high, medium, low), message
Merge requestworkflow_scan.noteWhat was not checked and why (a GitLab CI configuration outside the repository)
Merge requestworkflow_scan.errorWhy the check could not be completed
Merge requestdecision.controls[] with control: "workflows"The control's status (passed, pending, failed, skipped), blocking and reason
  • 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_scan job.

Video tutorial

Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →

Check Changes to the CI ConfigurationYouTube ↗