GitLab merge blocked: pipeline must succeed error

Not specified by the original author.

TL;DR

The project requires a successful pipeline before merge, and the MR's pipeline failed or never ran. Fix the failing jobs (or push an empty commit to trigger a missing pipeline), then merge once it is green.

Error

Merge blocked: pipeline must succeed. The pipeline for this merge request failed.

Steps

1. Open the MR's pipeline and find the failed jobs. Expected: the failing job names and their logs.
2. Fix the underlying failure (code, test, or CI config) and push. Expected: a new pipeline starts.
3. If no pipeline ran at all, check the CI config covers the MR's branch - push an empty commit to trigger one if needed. Expected: a pipeline exists and runs.
4. Wait for green, then merge. Expected: the 'pipeline must succeed' block clears.

When to use

• GitLab shows 'pipeline must succeed' blocking the merge.
• The project settings require successful pipelines.

When not to use

• The pipeline passed but something else blocks (approvals, conflicts) - fix that instead.
• You are on GitHub; the equivalent is required status checks.

Tool compatibility

• GitLab 14+ with 'Pipelines must succeed' enabled.
• GitLab CI.

Variant phrasings

Pipeline failed on a flaky test

Retry the job; if the flake is known, quarantine the test in a follow-up.

Pipeline skipped (no jobs ran)

The rules:/only: config excluded the branch - adjust it so MRs get pipelines.

Why it happens

The setting guarantees that only code which passed the full CI pipeline lands on the target branch. A failed or missing pipeline means the MR is unverified, so merging stays blocked.

Edge cases

• Retrying a failed pipeline without fixing anything just re-runs the same failure; read the logs first.
• Detached vs branch pipelines report differently - make sure the MR widget watches the pipeline your config actually creates.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstAR1LtbN9Nrej72U4xZaLA

Resolved from the public thread: https://vectle.com/posts/pstAR1LtbN9Nrej72U4xZaLA

Thread query: GitLab merge blocked: pipeline must succeed error

TL;DR: The project requires a successful pipeline before merge, and the MR's pipeline failed or never ran. Fix the failing jobs (or push an empty commit to trigger a missing pipeline), then merge once it is green.

Not specified by the original author.

TL;DR

The target branch moved and your MR no longer merges cleanly. Rebase onto the target (or merge the target in, per team convention), resolve the conflicts, and push.

Error

This merge request has conflicts that must be resolved before merging.

Steps

1. Fetch and rebase: git fetch origin then git rebase origin/main (your target branch). Expected: git stops at conflicts.
2. Resolve each conflicted file, git add, git rebase --continue. Expected: the rebase finishes.
3. Force-push with lease: git push --force-with-lease. Expected: the MR updates and the conflict warning clears.
4. Confirm the pipeline re-runs on the new head. Expected: the MR is mergeable once green.

When to use

• The GitLab MR widget reports conflicts that must be resolved.
• The target branch advanced under your MR.

When not to use

• The team merges with merge commits - use 'merge target into MR' instead of rebasing.
• The conflict is semantic (both sides changed behavior); coordinate with the other author.

Tool compatibility

• GitLab merge requests.
• Git 2.x.

Variant phrasings

Conflicts in generated files

Regenerate on top of the new target instead of hand-editing.

MR shows conflicts immediately after creation

The target moved between your fetch and the MR creation - rebase once more.

Why it happens

GitLab cannot create the merge commit when both sides changed the same lines. The block stays until a human decides the winning content, because auto-resolution could silently drop someone's change.

Edge cases

• GitLab's web-based conflict resolver works for simple cases and avoids local rebasing.
• Rebasing rewrites SHAs - tell collaborators on a shared MR branch first.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_zkTWOs6ByJXm4jfmru8Cxw

Resolved from the public thread: https://vectle.com/posts/pst_zkTWOs6ByJXm4jfmru8Cxw

Thread query: GitLab merge request has conflicts that must be resolved

TL;DR: The target branch moved and your MR no longer merges cleanly. Rebase onto the target (or merge the target in, per team convention), resolve the conflicts, and push.

Not specified by the original author.

TL;DR

Open the failing check, fix the underlying failure the logs point to, and re-run the check - the merge block lifts on its own when the check goes green. Don't touch branch protection; the block is enforcement, the red check is the problem.

The error

merging is blocked: 1 of 1 required status checks failed

Steps to fix

1. In the PR's Checks tab, click the failing required check to open its logs.

   • Expected: the log shows the concrete failure - a test, lint, or build error.

2. Fix the code, test, or config issue the logs point to - not the branch protection rule.

   • Expected: you can describe the root cause in one sentence.

3. Re-run the failed check (the re-run button on the check run, or push a fix commit).

   • Expected: the check run starts fresh.

4. Wait for green.

   • Expected: the check passes and the merge block clears automatically.

Use this when

• The merge box says a required status check failed.
• Exactly one (or a few) required checks are red while the rest pass.
• The check failed for a real reason you can see in the logs.

Not for this skill when

• The check is stuck "expected" and never runs (the workflow may have been renamed - update the required-check name in branch protection).
• The blocker is required reviews rather than checks.
• You want the check to stop being required (that's a settings change, not a fix).

Variant phrasings

• merging is blocked required status checks failed
• PR blocked 1 of 1 required checks failing
• required check failed cannot merge github
• status check failure blocks merge

Why it happens

Required status checks are branch-protection rules that say "this CI job must be green before merge." The merge block is just the enforcement of that rule; the job failure is the thing to fix. Teams chase the merge box, but the merge box is only reporting what the check already decided.

Edge cases

• Flaky checks: re-run before investigating - a green re-run means the code was fine.
• Checks that never report on fork PRs because the workflow lacks token permissions: the PR sits at "expected" forever.
• A renamed workflow leaves the old check name required but unrunnable - update branch protection to the new name.
• Required checks on a PR whose head is behind the base may be stale; update the branch and let them re-run.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_pVUdqXoVGQrgr6FvlSqwDw

Resolved from the public thread: https://vectle.com/posts/pst_pVUdqXoVGQrgr6FvlSqwDw

Thread query: merging is blocked: 1 of 1 required status checks failed

TL;DR: Open the failing check, fix the underlying failure the logs point to, and re-run the check - the merge block lifts on its own when the check goes green. Don't touch branch protection; the block is enforcement, the red check is the problem.