Skip to main content
3 video tutorials

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 matchesDefaultAllowed valuesWho can change itAPI field
Target branchThe branch the merge request merges into. Matches when the branch matches any patternNot set (any branch)Branch patterns, such as main, release/*Policy manager, company admin, platform adminmatch.target_branches
Source branchThe branch the merge request comes fromNot setBranch patterns, such as hotfix/**Samematch.source_branches
RepositoryThe repository's full path, with its group or owner, such as team/paymentsNot set (any repository of the connection)Path patterns, such as team/payments-*, platform/**Samematch.repos
AuthorWho opened the merge request: see AuthorPeople and bots, no usernamesAuthor kind and usernamesSamematch.author.kind, match.author.usernames
LabelsThe merge request's labels: see LabelsNot setHas any of, Has none ofSamematch.labels.any_of, match.labels.none_of
Only these files changedEvery changed file must match, e.g. for docs-only changes.Not setFile patterns, such as **.md, docs/**Samematch.paths.only_in
Touches files (Touches any of)At least one changed file matches.Not setFile patterns, such as db/migrations/**Samematch.paths.any_of
Does not touch files (Touches none of)No changed file matches.Not setFile patterns, such as infra/**Samematch.paths.none_of
SizeChanged files … or fewer, and Changed lines … or fewerNot set (any size)Whole numbers; empty or 0 means no limitSamematch.max_changed_files, match.max_changed_lines
Draft stateWhether drafts are coveredDrafts and readySee Draft stateSamematch.drafts

Author​

Setting (label in the UI)What it doesDefaultAllowed valuesAPI
Author kindLimits the policy to people or to bots, or covers bothPeople and botsPeople 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 accountsLimits 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 doesAPI
Has any ofThe merge request must have at least one label that matches one of these patterns. Empty: no label is neededmatch.labels.any_of
Has none ofThe merge request must have no label that matches one of these patternsmatch.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 matchesAPI value
Drafts and readyDrafts and ready merge requestsany
Ready merge requests onlyMerge requests that are not draftsexclude
Drafts onlyDrafts onlyonly

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:

PatternMatchesDoes not match
mainmainmain2, x/main
release/*release/v1.0release/v1/hotfix (more than one segment)
feature/**feature/a, feature/a/b/cfeatures/a
**/*.sqlschema.sql, db/x.sql (** is zero or more whole segments)schema.sqlx
**/deploy/**a/deploy/c/d.yaml (several ** may appear)
**.mdREADME.md, a/b/c.md (** joined to text crosses folders)
docs**docs, docs-old/a.md, docs/a/b.md
hot-fix*hot-fix-123hot-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: Main does not match main.
  • File patterns are matched from the repository root: *.md matches only Markdown files at the root, and docs/* only files directly in docs/. Use **.md or docs/** 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: Emergency matches emergency;
  • only * is a wildcard, matching any text, / included: team-* matches team-alice; other characters are literal, so dependabot[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 inWhen the pattern
Branches and repositoriesstarts with ^, ends with $, or contains .*, \, (, ), |, +, { or }
File patternsstarts 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:

  1. A policy that is not active is skipped. The catch-all, always active, decides when it is reached.
  2. 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.
  3. 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).
  4. 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:

conditionMessage in the UI
target_branchTarget branch … is not in …
source_branchSource branch … is not in …
repoRepository … is not in …
author_not_botThe author … is not a bot.
author_botThe author is a bot; the policy is for people.
authorAuthor … is not in …
label_excludedIt has the label …, which the policy excludes.
label_missingIt has none of the labels …
draftIt is a draft; the policy skips drafts.
readyIt is not a draft; the policy covers only drafts.
diff_unknownThe 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_excludedIt changes …, which the policy excludes (…).
path_outsideIt changes …, outside …
path_missingIt changes nothing in …
emergency_declarer_unknownWho 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_quotaThe 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.

Video tutorials

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

Scope a Policy by Branch, Files and LabelsYouTube ↗
Which Policy Applies?YouTube ↗
Let Dependency Bots Through SafelyYouTube ↗