What is Auto Merge?
GitLab Auto Merge is an automated merge request management service for GitLab. It monitors a project and continuously processes merge requests — merging, rebasing, cancelling obsolete pipelines, applying status labels, and retrying transient failures.
Deploy as a Docker container, point it at a GitLab project, and it takes over MR queue management.
Core Features
Section titled “Core Features”Automatic Merging
Section titled “Automatic Merging”Merges approved MRs when their pipeline succeeds using merge commits. No manual “merge” clicks needed. GitLab’s built-in “merge when pipeline succeeds” is automatically cancelled to prevent conflicts with Auto Merge’s queue management.
Auto Rebase
Section titled “Auto Rebase”Rebases MRs that fall behind the target branch. Keeps the merge queue moving without developer intervention.
Pipeline Management
Section titled “Pipeline Management”Cancels duplicate, obsolete, and superseded pipelines. Draft MR pipelines are cancelled immediately. Resource-aware: cancels lower-priority pipelines when runners are scarce.
Smart Status Labels
Section titled “Smart Status Labels”Applies a status label to every MR that waits for a human:
Auto-Merge::Has conflicts— has merge conflictsAuto-Merge::Waiting for approval— waiting for approvalAuto-Merge::Unresolved discussions— has open blocking discussionsAuto-Merge::Pipeline failed— pipeline failed and needs attentionAuto-Merge::Blocked by CI— GitLab blocks the merge on CI despite a green pipelineAuto-Merge::Last pipeline failed— the last completed pipeline failed on the same codeAuto-Merge::Repeated pipeline failure— out of the merge queue after repeated failuresAuto-Merge::Waiting for dependency— a declared dependency is not merged
The scoped Auto-Merge:: prefix keeps exactly one status label on an MR. Developers see at a glance what each MR needs.
Queue Position
Section titled “Queue Position”The Auto-Merge section of each MR description states the MR’s position in the merge queue. Auto Merge updates it as MRs ahead of it merge.
Job Retry
Section titled “Job Retry”Automatically retries jobs that fail due to transient errors (OOM, network issues, temporary auth failures). Only retries known-safe error patterns. Each job is retried up to 3 times. When the retry limit is reached, a note is posted on the MR.
Priority Support
Section titled “Priority Support”An MR whose title starts with Main fix: fixes a red default branch and is processed first, then MRs labeled Merge First. MRs labeled Merge Last are processed after every MR of a higher priority class. An MR’s own priority class comes from its title and labels. The Label System page names them. An MR without Merge First or Merge Last takes the highest priority class among its own and those of the open MRs stacked on it (MRs targeting its source branch); one with them keeps its class unless a main fix is stacked on it. Lower-priority pipelines may be cancelled to free runner capacity for high-priority MRs.
Conflict Detection
Section titled “Conflict Detection”Identifies and labels MRs with merge conflicts. Cancels their pipelines (they cannot be merged anyway).
REST API & Web Dashboard
Section titled “REST API & Web Dashboard”REST API for monitoring MRs, pipelines, runners, and execution history. A React-based dashboard is available as a separate deployment for visual monitoring. Full audit trail of every action.
GitLab Webhook Integration
Section titled “GitLab Webhook Integration”Responds to MR and pipeline events for near-instant reactions. Also polls every 15 seconds as fallback.
Why Auto Merge?
Section titled “Why Auto Merge?”| Problem | Solution |
|---|---|
| Developers waste time clicking “Merge” and “Rebase” | Fully automated merge + rebase |
| Stale pipelines waste CI runner capacity | Automatic cancellation of obsolete pipelines |
| Merge conflicts go unnoticed | Proactive conflict detection and labeling |
| No visibility into merge queue order | Queue position in every MR description |
| Transient CI failures block merging | Automatic retry of known-safe failures |
| Hotfixes wait behind regular MRs | Priority system with resource-aware scheduling |
| Teams don’t know MR status at a glance | Status labels updated in real time |
Target Audience
Section titled “Target Audience”- DevOps / Platform Engineers managing GitLab CI/CD for teams
- Engineering Managers wanting faster merge throughput and visibility
- Development teams (5+ developers) with high MR volume
- Organizations using self-hosted GitLab (CE or EE) — custom CA certificate support built in
- GitLab.com users wanting merge automation beyond GitLab’s built-in auto-merge