Matching
A policy's conditions decide which merge requests it covers. They are set on the editor's Scope tab. Merge Pilot tries a VCS connection's policies from top to bottom, and the first active policy whose conditions all hold decides the merge request (see Change policies).
How conditions combine
- A merge request must meet every condition the policy sets.
- A condition that is not set matches everything. A policy with no condition covers every merge request, and the editor says so (Covers every merge request).
- Within one condition, a list of patterns matches when any of them matches.
- The catch-all has no conditions and cannot have any: it covers every merge request no policy above it matches.
On the Scope tab, Add condition offers the conditions not yet set; the × next to a condition removes it, so it matches everything again. Lists are typed as values separated by commas.
Conditions
| Condition (label in the UI) | What it matches | Default | Allowed values | Who can change it | API field |
|---|---|---|---|---|---|
| Target branch | The branch the merge request merges into. Matches when the branch matches any pattern | Not set (any branch) | Branch patterns, such as main, release/* | Policy manager, company admin, platform admin | match.target_branches |
| Source branch | The branch the merge request comes from | Not set | Branch patterns, such as hotfix/** | Same | match.source_branches |
| Repository | The repository's full path, with its group or owner, such as team/payments | Not set (any repository of the connection) | Path patterns, such as team/payments-*, platform/** | Same | match.repos |
| Author | Who opened the merge request: see Author | People and bots, no usernames | Author kind and usernames | Same | match.author.kind, match.author.usernames |
| Labels | The merge request's labels: see Labels | Not set | Has any of, Has none of | Same | match.labels.any_of, match.labels.none_of |
| Only these files changed | Every changed file must match, e.g. for docs-only changes. | Not set | File patterns, such as **.md, docs/** | Same | match.paths.only_in |
| Touches files (Touches any of) | At least one changed file matches. | Not set | File patterns, such as db/migrations/** | Same | match.paths.any_of |
| Does not touch files (Touches none of) | No changed file matches. | Not set | File patterns, such as infra/** | Same | match.paths.none_of |
| Size | Changed files … or fewer, and Changed lines … or fewer | Not set (any size) | Whole numbers; empty or 0 means no limit | Same | match.max_changed_files, match.max_changed_lines |
| Draft state | Whether drafts are covered | Drafts and ready | See Draft state | Same | match.drafts |
Author
| Setting (label in the UI) | What it does | Default | Allowed values | API |
|---|---|---|---|---|
| Author kind | Limits the policy to people or to bots, or covers both | People and bots | People and bots (any), People only (human: a bot author does not match), Bots only (bot: only authors the VCS reports as bots) | match.author.kind |
| Authors / Bot accounts | Limits the policy to these usernames. With Bots only, only these bots match, and the VCS must still report each of them as a bot. A service account the VCS does not flag as a bot never matches Bots only: choose People and bots and list it under Authors (the editor's hint under Bot accounts says so) | Empty (any) | VCS usernames, such as alice, team-* or dependabot[bot], renovate[bot] | match.author.usernames |
With Bots only and no bot listed, the editor warns: every bot account matches, including CI tokens (github-actions[bot]) and GitLab project or group access tokens anyone with Maintainer can create. List the bots you mean.
Labels
| Setting (label in the UI) | What it does | API |
|---|---|---|
| Has any of | The merge request must have at least one label that matches one of these patterns. Empty: no label is needed | match.labels.any_of |
| Has none of | The merge request must have no label that matches one of these patterns | match.labels.none_of |
An emergency policy that matches on a label also uses that label to find who declared the emergency (see Who may declare an emergency).
Changed files
Paths are the repository paths of the changed files. A renamed or moved file counts with both its new and its old path, so moving code into docs/ does not make it a documentation change. A deleted file counts with its old path.
- Only these files changed: every changed file must match one of the patterns.
- Touches any of: at least one changed file must match one of the patterns.
- Touches none of: no changed file may match any of the patterns.
Size
- Changed files: the number of changed files (renamed files counted with both paths, as above) must be at most this.
- Changed lines: the added plus deleted lines, as the VCS counts them, must be at most this. When the VCS sends a changed file without a line count (for example a binary or very large file), the line count is not known and a Changed lines limit does not match.
Draft state
| Option (label in the UI) | What it matches | API value |
|---|---|---|
| Drafts and ready | Drafts and ready merge requests | any |
| Ready merge requests only | Merge requests that are not drafts | exclude |
| Drafts only | Drafts only | only |
When the changed files are not known
Conditions on files and size need the list of changed files. When the VCS cannot send it (a very large change, or a list it sends only in part), a policy with a file or size condition does not match, and a later policy decides: an unknown size or set of files cannot prove that a narrow policy applies. The policy list warns about such policies (see Order warnings).
When the VCS cannot be reached to read the changed files and a policy needs them, Merge Pilot does not pick another policy: the job fails and is tried again (see Jobs).
Patterns
Patterns are globs: * matches within one segment, ** across folders. Separate several with commas.
Branches, repositories and files
Branch names, repository paths and file paths are matched the same way, as paths split at /, against the whole value, from the start:
| Pattern | Matches | Does not match |
|---|---|---|
main | main | main2, x/main |
release/* | release/v1.0 | release/v1/hotfix (more than one segment) |
feature/** | feature/a, feature/a/b/c | features/a |
**/*.sql | schema.sql, db/x.sql (** is zero or more whole segments) | schema.sqlx |
**/deploy/** | a/deploy/c/d.yaml (several ** may appear) | |
**.md | README.md, a/b/c.md (** joined to text crosses folders) | |
docs** | docs, docs-old/a.md, docs/a/b.md | |
hot-fix* | hot-fix-123 | hot-fix/123 |
* | Any branch, file or repository (on its own, * means any value) |
*and?match within one segment, and[…]matches one character of a set, as in shell globs.- Matching is case-sensitive:
Maindoes not matchmain. - File patterns are matched from the repository root:
*.mdmatches only Markdown files at the root, anddocs/*only files directly indocs/. Use**.mdordocs/**for any depth. - Spaces around a pattern are removed, and a pattern listed twice is kept once.
Usernames and labels
Usernames (in Author) and labels are matched differently:
- case-insensitive:
Emergencymatchesemergency; - only
*is a wildcard, matching any text,/included:team-*matchesteam-alice; other characters are literal, sodependabot[bot]is just that name.
Not regular expressions
Patterns are globs, not regular expressions. A regular expression would never match as a glob and would silently make the policy match nothing, so it is refused when the policy is saved: "…" looks like a regular expression; patterns use glob syntax, e.g. main, release/*, docs/**.
| Refused in | When the pattern |
|---|---|
| Branches and repositories | starts with ^, ends with $, or contains .*, \, (, ), |, +, { or } |
| File patterns | starts with ^, ends with $, or contains \, (, ), |, +, { or } (.* is allowed there, as in *.generated.* or .*rc) |
A pattern that is not a valid glob, such as an unclosed [, is refused too.
How a merge request is evaluated
For each merge request Merge Pilot reads its target and source branch, its repository path, its author (and whether the VCS flags the author as a bot), its labels, whether it is a draft and, when a policy needs them, its changed files and their line counts. It then goes through the connection's policies in order:
- A policy that is not active is skipped. The catch-all, always active, decides when it is reached.
- The conditions are checked in this order, and the first one that fails ends the check for that policy: target branch, source branch, repository, author kind, usernames, labels (Has none of first, then Has any of), draft state, then, only when the policy has file or size conditions, whether the changed files are known, Changed files, Changed lines, and the file patterns.
- For an emergency policy whose conditions all hold, the emergency rules are applied last: when the person who declared the emergency may not, the policy does not match (see Who may declare an emergency).
- The first policy that matches decides; the policies after it are not tried.
The same matching runs every time the merge request is processed: when it is opened, reopened or updated, when its target branch changes, and when the policies change (see Open merge requests after a change). A merge request can therefore move to another policy, for example when a label is added.
Why a policy does not match
Which policy applies? on the Change policies page (see Trying policies out) gives the first condition each policy above the deciding one fails. It applies the emergency rules too; since a described change has no one who declared the emergency, an emergency policy whose rules limit who may declare one shows emergency_declarer_unknown. The API returns the condition as miss.condition:
condition | Message in the UI |
|---|---|
target_branch | Target branch … is not in … |
source_branch | Source branch … is not in … |
repo | Repository … is not in … |
author_not_bot | The author … is not a bot. |
author_bot | The author is a bot; the policy is for people. |
author | Author … is not in … |
label_excluded | It has the label …, which the policy excludes. |
label_missing | It has none of the labels … |
draft | It is a draft; the policy skips drafts. |
ready | It is not a draft; the policy covers only drafts. |
diff_unknown | The changed files are not known, and the policy matches on paths or size. |
too_many_files | … files changed; the policy allows … |
too_many_lines | … lines changed; the policy allows … |
path_excluded | It changes …, which the policy excludes (…). |
path_outside | It changes …, outside … |
path_missing | It changes nothing in … |
emergency_declarer_unknown | Who declared the emergency is not known …; the policy's emergency rules need it. |
emergency_by_author | …, the author, declared their own change an emergency; the rules do not allow it. |
emergency_not_in_pool | … declared the emergency but is not among the people who may. |
emergency_quota | The repository has had … emergencies in the window; the rules allow … |
In Which policy applies?, leaving Changed files empty and Changed lines at 0 makes the diff count as unknown, as for a change too large for the VCS to send.
Related pages
- Change policies: the list, order, change types and the testers.
- Controls: what a matched policy checks.
Video tutorials
Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →