CI
The CI control makes a merge wait for the merge request's CI to pass on its latest commit: GitLab pipelines, GitHub Actions workflows, checks of other GitHub Apps and, if you allow them, commit statuses. It counts only runs from sources the policy trusts, and it does not count runs of a change that edits its own CI configuration, since such runs prove nothing about it.
The control is set per change policy, in the policy editor's Checks tab (row CI).
Modes
| Mode (label in the UI) | API value | What it does | Effect on the merge gate |
|---|---|---|---|
| Off | off | CI is not looked at | None |
| Report | report | CI is read and the result shown on the merge request, marked (report only) | None |
| Enforce | block | Every counted run on the latest commit must succeed | Waiting while runs are missing or running; Blocked when one failed or was cancelled |
A new policy starts with Off.
In Enforce mode a merge request with no counted run waits ("Waiting for CI to run on the latest commit."). Use Enforce only where every covered repository runs CI on merge requests, or narrow the policy (see Matching).
Settings
All settings are in the policy; the company has no CI defaults.
| Setting (label in the UI) | What it does | Default | Allowed values | Set where | Who can change it | API field |
|---|---|---|---|---|---|---|
| Mode (row CI) | See Modes | Off | Off, Report, Enforce | Policy | Policy manager, company admin, platform admin | controls.ci.mode (off, report, block) |
| Only these pipelines or checks | Limits the control to runs with these names. Each name listed must then be present on the latest commit. On GitLab a pipeline is named by its workflow:name; one without a name is called pipeline | Empty: every counted run | Names; * is a wildcard; case is ignored | Policy | Same | controls.ci.checks |
| Also count checks from these GitHub Apps | GitHub Apps, by their slug, whose checks count | Empty: GitHub Actions and GitLab pipelines only | App slugs, for example circleci-checks | Policy | Same | controls.ci.sources |
| Count commit statuses (anyone who may push can post one) | Also count commit statuses: GitHub commit statuses and GitLab external pipelines | Off | On, off | Policy | Same | controls.ci.allow_statuses |
| Files that define CI | The files whose change means the change edits its CI configuration | Empty: .github/workflows/**, .github/actions/**, .gitlab-ci.yml, .gitlab/ci/** | Path patterns from the repository root (** spans folders). Add files your CI includes from elsewhere | Policy | Same | controls.ci.config_paths |
| Count runs when the change edits these files (its runs then test the edited CI) | Count the runs even when the change edits a CI configuration file | Off | On, off | Policy | Same | controls.ci.allow_config_changes |
The last four settings appear when the mode is not Off. Lists are typed as comma-separated values.
Which runs count
-
Only runs on the merge request's latest commit count. For each name and source, the most recent run is used: a re-run replaces the earlier one.
-
A run counts only if its source is trusted:
- GitLab pipelines and GitHub Actions workflows always count;
- another GitHub App's checks count only when the App's slug is in Also count checks from these GitHub Apps. A check of the same name from another App does not count;
- commit statuses count only with Count commit statuses on, because anyone who may push to the repository can post one.
Runs left out for their source are named in the message ("Not counted (source not trusted by the policy): deploy (status).").
-
With Only these pipelines or checks set, only runs whose name matches count, and each listed name must have a run. A listed name with no run yet is shown as running.
-
Merge Pilot's own check (on GitHub, Merge Pilot / change approval) is never counted.
Names are what the VCS shows: a GitHub Actions workflow's name, the name of another GitHub App, a commit status's context. A GitLab pipeline is known by its name (workflow:name in its CI configuration), from its events and when it is read from GitLab; a pipeline without a name is called pipeline. Only these pipelines or checks can therefore name GitLab pipelines.
Changes to the CI configuration
Unless Count runs when the change edits these files is on, a change that edits one of the Files that define CI gets no credit from its runs: the control stays pending and names the files ("This change edits its CI configuration (.gitlab-ci.yml), so its CI runs prove nothing about it and do not count. …"). In Enforce mode such a change cannot merge under this policy. Cover CI changes with their own policy (matching on those paths) that turns the option on and asks for review instead.
When the change is too large for its files to be read, whether it edits CI is not known, and the runs do not count either.
How run states are read
| Run state | Counts as |
|---|---|
| Success, skipped (GitHub: success, neutral, skipped) | Passed |
| Failed, cancelled (GitHub: failure, timed out, startup failure, cancelled, stale; GitHub statuses failure and error) | Failed: "Failed: build." |
| Anything else: created, pending, queued, running, waiting for a manual action (GitHub: action required) | Running: "Running: build." |
All counted runs passing gives "All CI runs on the latest commit passed."
Events of one run may arrive out of order: a state that is not final (such as running) never replaces a final one (passed, failed, cancelled or skipped). A retried run is recorded again when it ends.
When it runs
Merge Pilot follows CI through the VCS's events (pipelines and jobs on GitLab; workflow runs, check suites, check runs and statuses on GitHub). Each event is stored on the merge request and the merge request is evaluated again. The periodic re-check of open merge requests, and Resync on the merge request page, read the latest commit's runs from the VCS again, so a lost event does not leave the control stuck. There is nothing to re-scan.
Merge Pilot keeps the 50 most recently updated runs of a merge request.
GitLab and GitHub
| GitLab | GitHub | |
|---|---|---|
| Runs | Pipelines (with their jobs) | Actions workflow runs, check suites of other Apps (one per App, named after the App, with its check runs as jobs), commit statuses |
| Commit statuses | External pipelines (pipelines GitLab creates for a commit status) count only with Count commit statuses on | Commit statuses count only with Count commit statuses on |
| Merged results | Merged results and merge train pipelines, which run on a merge commit of the latest commit into the target, count for the latest commit. They are taken from their events, and the periodic re-check and Resync read them from GitLab again, so a lost event is recovered | — |
| Also count checks from these GitHub Apps | Not used | Applies |
What the merge request shows
- Policy card: the control's line and message.
- CI/CD pipelines card: the stored runs with their status, and their jobs by stage when the VCS reported them.
- The status comment in the VCS lists the control with the same message.
Audit
The control writes no entry of its own; its result is part of mr_gate_approved, mr_gate_pending and mr_gate_blocked (see Audit log). CI events are processed as pipeline_tracking jobs.
API
- Policy:
controls.ciwithmode,checks,sources,allow_statuses,config_paths,allow_config_changes. - Merge request (
GET /api/v1/merge-requests/{id}):pipelines(each withpipeline_id,name,status,sha,app,jobs_by_id), and the result indecision.controls(control: "ci").
Video tutorial
Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →