Why can't I merge my GitLab merge request? Every blocking reason

You were asked to merge it, the code looks fine, and the button is grey. GitLab is not being mysterious: every merge request runs a fixed list of merge checks, and one of them is failing. This guide lists them all — the same list GitLab’s API reports as detailed_merge_status — with what each means and what to do.

Where to see what is blocking

On the merge request’s Overview, the merge widget shows every check and marks the ones that fail. If you script against GitLab, the merge request API returns the first failing check in detailed_merge_status. Some checks only exist on paid tiers, noted below.

Checks on every tier

Status	What it means	How to fix it
draft_status	The merge request is marked as a draft	Mark it as ready (remove “Draft:” from the title)
discussions_not_resolved	The project requires all threads to be resolved, and some are not	Resolve them, or reply and resolve if the point is settled
ci_must_pass	The project requires a successful pipeline, and the latest one failed — or there is none	Fix the failure and push, or retry the failed jobs; run a pipeline if none exists
ci_still_running	The required pipeline has not finished	Wait — or set auto-merge, below
conflict	The source and target branches conflict	Resolve the conflicts in GitLab or locally, then push
need_rebase	The project’s merge method needs the branch rebased onto the target	Select Rebase, or use the /rebase quick action
not_open	The merge request is closed or already merged	Reopen it if it was closed by mistake
commits_status	The source branch is missing or has no commits	Push the branch again
locked_lfs_files	Someone else holds a Git LFS lock on a file you changed	Ask them to unlock it

Checks on Premium and Ultimate

Status	What it means	How to fix it
not_approved	Required approval rules are not satisfied	Get approvals from the eligible approvers or Code Owners
requested_changes	A reviewer requested changes	Address them, then ask the reviewer to remove the request; someone with merge permission can bypass it
merge_request_blocked	It depends on another merge request that is not merged yet	Merge the dependency first, or remove the dependency
title_regex	The title does not match the project’s title rule	Edit the title
locked_paths	A file or directory on the default branch is locked by someone else	Ask the person who locked it to unlock it

Checks on Ultimate

Status	What it means	How to fix it
status_checks_must_pass	An external status check has not passed	Fix what the external service reports
jira_association_missing	The title or description must reference a Jira issue	Add the Jira issue key
security_policy_violations	A security policy is not satisfied	Fix the findings, or get the approvals the policy requires
security_policy_pipeline_check	Pipelines required by a security policy have not all succeeded	Make the latest commit’s pipelines pass

Scheduled and temporary states

merge_time means someone set a Merge after date on the merge request and it has not arrived yet: wait, or change the date.

checking, unchecked, preparing and approvals_syncing mean GitLab is still working something out — testing whether the merge is possible, building the diff, or syncing approvals. Refresh after a few seconds. mergeable means you are clear.

The project settings behind most of these

Most of the checks are switched on in the project’s merge request settings:

• Pipelines must succeed turns on ci_must_pass. With it on, a merge request that has no pipeline at all cannot merge. Skipped pipelines are considered successful relaxes it for skipped ones.
• All threads must be resolved turns on discussions_not_resolved.
• The merge method decides need_rebase: merge commit never needs one; fast-forward and semi-linear do whenever the target branch moves. Since GitLab 19.2, automatic rebase before merge can do it for you.

Let GitLab merge it for you: auto-merge

If the only thing left is a running pipeline or a pending approval, select Set to auto-merge (it used to be called Merge when pipeline succeeds). GitLab merges the merge request the moment every check passes. Anyone with the Developer role can set it. A new commit to the merge request cancels it, and so do new commits on the target branch under fast-forward or semi-linear merges, unless automatic rebase is on.

Seeing every blocking reason on your phone

When you are asked to merge from a phone, the question is always “can I, and if not, why?” MergeBell’s merge sheet answers it before you tap: it lists every reason GitLab gives — approvals, unresolved threads, a failed or running pipeline, conflicts — and when GitLab would merge despite a failed pipeline, it says so in warning colours instead of calling it ready. Approve, merge, squash and auto-merge are all in the free tier. See also how to review a merge request on your phone.