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.

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.