Documentation

Getting Started

Deploy Auto Merge in 30 seconds. Three environment variables is all you need.

1 Quick Start

$ docker run -d --name auto-merge \
    -p 8711:8711 \
    -e GITLAB_SERVER_URL=https://gitlab.example.com \
    -e GITLAB_PROJECT=your-group/your-project \
    -e GITLAB_ACCESS_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx \
    neckarit/gitlab-auto-merge:latest --mode=DryRun

The dashboard is available at http://localhost:8711. Start in DryRun mode to observe what the tool would do without making any changes.

2 Environment Variables

environment

Variable	Required	Description
GITLAB_SERVER_URL	✓	Your GitLab instance URL
GITLAB_PROJECT	✓	Project path (e.g., group/project)
GITLAB_ACCESS_TOKEN	✓	GitLab API token (Maintainer role)
CA_CERT_BASE64	—	Base64-encoded custom CA certificate
CA_CERT_PATH	—	Path to CA certificate file (mount via volume)

3 Execution Modes

Pass the mode via command-line argument. Start with --mode=DryRun and work your way up.

DryRun

Read-only. Logs what it would do. No changes.

OnlyLabels

Applies status and queue position labels. Does not merge, rebase, or cancel.

RebaseOnly

Labels + automatic rebase. No merging or pipeline cancellation.

NoMerge

Labels + rebase + pipeline cancellation. Does not merge.

NoPipelineCancellation

Labels + rebase + merge. Does not cancel pipelines.

Run

Full automation. Merge, rebase, cancel pipelines, retry jobs, manage labels.

4 Status Labels

Every MR receives exactly one status label reflecting its current state. Labels update automatically.

Mergeable Ready to merge

Waiting for CI Pipeline running

Rebase Required Behind target branch

Rebasing Rebase in progress

Conflict Merge conflict detected

Not Approved Missing approvals

5 Webhook Setup

Optional but recommended. Enables near-instant reactions to MR and pipeline events.

In your GitLab project, go to Settings → Webhooks and add:

URL: http://your-host:8711/api/auto-merge/events/from-gitlab

Events: Merge request events, Pipeline events

Without webhooks, Auto Merge polls every 15 seconds. Webhooks reduce reaction time to near-instant.

6 REST API

The dashboard runs on port 8711. All API endpoints are available under /api/auto-merge/.

api-endpoints

GET /api/auto-merge/configuration

GET /api/auto-merge/merge-requests

GET /api/auto-merge/pipelines

GET /api/auto-merge/runners

GET /api/auto-merge/history

POST /api/auto-merge/events/from-gitlab # webhook endpoint