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 status labels to every MR reflecting its current state:
🚌 ➤ Mergable ✓— ready to merge🚌 ➤ Next Up 🎯— next in the merge queue🚌 ➤ Waiting for CI ⏳— pipeline running or pending🚌 ➤ Rebase required 🛠️— needs rebase onto target branch🚌 ➤ Conflict ⚔️— has merge conflicts🚌 ➤ Not Approved 🤔— waiting for approval🚌 ➤ Todo 🚧— unresolved discussions or failed pipeline🚌 ➤ Empty ⬜— MR has no commits🚌 ➤ Merged 🎉— successfully merged
All Auto Merge labels are prefixed with 🚌 for easy identification in GitLab.
Developers see at a glance what each MR needs.
Queue Position Labels
Section titled “Queue Position Labels”Shows each MR’s position in the merge queue with numbered labels. Positions update automatically as MRs are merged.
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”MRs labeled Important are processed first. MRs labeled LowPriority are processed only when no other MRs are queued. 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 labels on every MR |
| 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