Merge request settings

Overview

Merge request settings are a repository's merge policy: how a merge request lands in git, whether its commits may be squashed, and what else has to be true before the Merge button does anything. Set them on a group and every repository beneath inherits them, so "no unresolved threads and a green pipeline" can be one decision for the whole organisation rather than forty.

There is one set of settings per repository and one per group — nothing to create, nothing to name. You change fields, and the set comes into existence the first time you do. Nothing is copied onto a merge request when it is opened: the policy is read fresh every time somebody asks for the merge check or merges. A change you make now therefore applies to every merge request that is open right now.

Who has to approve a merge request, and how many of them, is not one of these settings. It is set with approval rules, which have their own page and their own way of inheriting.

Before you start

How it works

One set per scope, resolved when you read it

Every repository and every group has at most one set of these settings, and each field in it is in one of two states: set to a value, or unset. false and 0 are values like any other, so a field set to one of them is an override, not an absence; unset is the only thing that means inherit. Reading a repository gives you the resolved answer, with inheritance already applied and every field carrying a concrete value. Reading a group gives you that group's own values only, with unset fields absent or null, never filled in with a default.

That asymmetry is deliberate, and it is the difference between two questions. What will happen to my next merge? is a repository question and deserves a complete answer. What does this group impose on everything below it? is a group question, and folding in what the group inherits from its own parents would hide where a value actually comes from.

The repository's override switch is all or nothing

A group chain merges field by field: walking from the repository's parent group upwards, the nearest group that sets a field wins for that field, and a group that turns its own override switch on stops the walk there. A repository is different. Its stored values count only when override_group_settings is on. With it off — the default — everything the repository has saved is ignored and the whole policy comes from the group chain.

Turn that switch off and the same repository resolves differently, even though nothing else changed:

The repository's saved values are not deleted when the switch goes off; they sit there as a draft and come back the moment you turn it on. This is why a repository can look configured and behave as though it is not — and why the first thing to check when a change has no effect is that switch.

false is an override, null hands a field back

Setting a switch to false means not this, whatever the group says. It is a value like any other and it wins over an ancestor's true. To stop overriding a single field and inherit it again, send that field as null. To hand back every field at once, reset the whole set.

The same is true of a value that happens to equal the default. To escape a group's require_pipeline_success: true for one repository, turn its override switch on and set require_pipeline_success: false — leaving it unset would inherit the true straight back.

The merge method is a default, the rest are gates

merge_method is the method a merge uses when the merge request does not name one, and whoever merges may name one. Setting fast_forward on the repository is how you get a linear history by default; it does not stop a Maintainer from asking for a merge commit on a particular merge. If a method must be the only method, protect the target branch as well so that fewer people can merge at all.

The squash policy is not a gate either, and it is not symmetrical. never is the only value that refuses anything, and only when a merge explicitly asks to squash. require squashes whatever the merge asked for, without complaint. allow and encourage decide nothing but which way the box starts.

The rest of the list splits three ways. override_group_settings and delete_source_branch_default refuse nothing at all. stack_auto_retarget and stack_restack_strategy decide what happens after a merge, never whether it happens. Everything else — block_on_rejection, the discussion, work-item and pipeline gates, and stack_enforce_merge_order — refuses the merge outright.

What each setting does

Where each one is checked

squash_option appears only at the merge: the merge check has no squash item at all, because nothing has said whether this merge wants a squash until the merge itself asks.

Nothing is snapshotted onto a merge request when it is opened. Turning unresolved_threads on blocks every open merge request that has an open thread, from the next merge check onwards, and turning it off unblocks them just as quickly. Approval rules behave the same way.

How to

Read the policy a repository applies

This is the answer to what will happen to my next merge — every field resolved to a concrete value, whether that value came from this repository or from a group four levels up. The response does not say which. override_group_settings tells you only whether the repository's own values count at all, and even when it is on, every field the repository leaves unset still comes from the groups. Reading the groups is how you find out where a value lives.

Read what a group sets on its own

A group's settings come back raw — only what this group declares, with everything it leaves alone absent or null rather than shown as a default. That is what you want when you are tracing where a value in a repository came from: walk up the groups until one of them names the field.

Set a repository's own merge policy

Send only the fields you want to change — the rest keep the values they had. Nothing here needs the repository to have merge requests, branches or commits.

If the repository sits inside a group that sets a policy, remember the switch: without override_group_settings: true in the same call, everything else you send is stored and ignored.

Two combinations are worth knowing before you pick a method. fast_forward refuses a merge whenever the source branch is behind the target, so contributors have to rebase before they can land — that is the point of it, but it is a workflow change and not just a history preference. fast_forward together with squash_option: require gives the cleanest possible history: one commit per merge request, no merge commits at all.

Hold a merge while a reviewer asks for changes

block_on_rejection makes a reviewer's "changes requested" verdict hold the merge until that reviewer withdraws it or changes it to an approval, however many approvals arrive in the meantime. A later push does not clear it — somebody has to look again.

How many approvals a merge request needs, whose approvals count, whether the author or a committer may approve, and whether approvals survive a push are set with approval rules, not here.

Block a merge on discussion, work items or a pipeline

These four are the gates that tie a merge to the rest of the work rather than to the code review.

require_pipeline_success is off until somebody turns it on, and deliberately so: a merge is allowed only when every check has passed, so a CI gate that defaulted on would make every repository without a pipeline unmergeable. Turn it on once the repository has a pipeline that runs on merge requests, not before.

Every pipeline that applies has to pass, not just one. A pipeline applies to a merge request when one of its triggers matched the merge request — its branch, its paths and its actions — or when a run of it tested the head commit, such as a push to the source branch. Each one is judged by its latest run for the head, so retrying a failed run, or approving an untrusted one, replaces the result. A pipeline that matched but could not start — its monthly runs ran out, its definition does not resolve, the merge result conflicts — blocks the merge and the merge check says why. Reading the merge request's pipelines lists each one with where it stands.

Right after a push the gate waits. Until the platform has decided which pipelines apply to the new head, the merge check reports that it is waiting for the pipelines to be scheduled, and the merge is refused. This takes seconds, and it is what stops a merge slipping through between the push and its pipelines starting.

Switching the gate on also switches on a second, non-blocking report. A merge request's run records the target branch tip it was tested against, and if the target has moved since, the merge check says so — the run passed, but it no longer describes what will actually land. That report does not stop a merge. Run the merge request's pipelines again if you want the green to still mean something.

Decide what happens when no pipeline applies

Some merge requests have no pipeline at all: the repository defines none yet, or every pipeline filters itself out — a documentation change in a repository whose CI runs only when code changes. With require_pipeline_success on, allow_merge_without_pipeline decides what that means. Off — the default — the merge is blocked, because the repository said a green pipeline is required and there is none to show. On, a merge request that no pipeline applies to merges as if the gate were satisfied.

Turning it on does not weaken the gate for merge requests a pipeline does apply to: those still wait for every one of them to pass, and a head the platform is still evaluating is never treated as having no pipeline. It has no effect while require_pipeline_success is off.

require_issue_criteria_green reads against the merge request's head commit, not the default branch. Push a fix and the criteria a pipeline proves are re-evaluated against the new head; a pass recorded at an older commit does not carry forward. A criterion somebody ticks by hand is not tied to a commit and stays ticked. require_linked_issue is not commit-scoped at all — it asks only whether the merge request names a work item.

Change how stacked merge requests behave

A stack is a chain of merge requests, each targeting the branch below it. Three settings decide what happens to the ones above when one of them lands.

stack_auto_retarget is on by default and is what keeps a stack coherent: when a merge request merges, its open dependents are re-pointed at the branch it merged into. Turn it off and they keep pointing at a branch that has just been merged and possibly deleted, which is almost never what you want.

stack_enforce_merge_order is also on by default and refuses to merge a merge request while an open one still sources from its target branch — that other merge request is below it in the stack and has to land first. Turn it off and the merge check drops the item entirely, so you may merge in any sequence; the stack view is then the only place the chain is still visible.

stack_restack_strategy decides who does the rebasing a retarget can leave behind — most visibly after a squash merge, which puts the same diff on the target under a new commit. signal reports it on the merge check, without blocking the merge, and leaves the author to rebase and force-push; the report appears only when the branch is genuinely behind. server_side rebases the dependent branch onto its new base as part of the retarget and force-updates it, every time, whether or not anyone would have noticed.

Both of those ride on the retarget, which is the one that has to happen first. The whole post-merge cascade runs only when stack_auto_retarget is on, so server_side with auto-retarget off does nothing at all. If you want server-side restacking, leave auto-retarget on.

Hand one field back to the group

Turning a switch off is not the same as letting the group decide it. false is a value, and it overrides an ancestor's true exactly as true would. To stop overriding one field and inherit it again, send that field as null. The repository keeps its override on everything else.

The same call works on a group and means the same thing: the group stops declaring that field, and the groups above it decide again.

Set one policy for every repository in a group

This is the setting worth reaching for first. A group's policy reaches every repository beneath it at any depth, including repositories created next week, and each repository inherits it field by field unless it overrides.

Turning override_group_settings on for a group does something different from a repository: it caps the walk. The group's own values are used, and any field still unset once the walk reaches it falls to its default rather than to what a group above says. Groups between it and the repository are unaffected and still supply whatever they set, so this isolates a subtree from an organisation-wide baseline without freezing the groups inside it. There is no switch for it on the group's form, so set it through the CLI or the API.

Reset a repository to the group policy

Resetting is how you go back to inheriting everything. It is not a way to switch policy off — a repository with no settings of its own inherits the whole group chain. To genuinely depart from a group's policy, turn override_group_settings on and set the fields explicitly instead. Resetting is idempotent: resetting a repository that never had settings succeeds and changes nothing.

Clear a group's settings

Repositories below the group do not lose their own settings; they lose what they were inheriting. Each field the group used to declare now falls through to the nearest group above that declares it, and to its default if none does — from the next merge check onwards.

Reference

Repository

Group

Limits

None of these calls counts against a plan quota.

Troubleshooting

Examples

An organisation baseline on the root group — resolved discussion, no outstanding change requests and a green pipeline everywhere, with squashing encouraged. Pair it with an approval rule on the same group for the review itself:

One repository beneath it that holds only documentation and has no pipeline, keeping everything else the organisation asks for:

The same repository later gets a pipeline and wants the group's gate back, without giving up the override on anything else:

An organisation whose pipelines run only when code changes, so that a merge request touching nothing but documentation has no pipeline — and should merge anyway:

A repository that wants the cleanest possible history — one commit per merge request, no merge commits:

FAQ

Related