Getting Started

Quick Start

The Docker image is available on Docker Hub: neckarit/gitlab-auto-merge.

Run Auto Merge with a single Docker command:

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

This starts Auto Merge in DryRun mode — it reads your MRs and shows what it would do, without making any changes.

Verify It Works

Check the container logs:

docker logs gitlab-auto-merge

You should see Auto Merge starting up and listing the labels it would create.

Query the API to see your merge requests categorized by status:

curl http://localhost:8711/api/auto-merge/merge-requests | python3 -m json.tool

Check the current configuration:

curl http://localhost:8711/api/auto-merge/configuration | python3 -m json.tool

Next Steps

1. Review the output — check the API and logs to see how Auto Merge categorizes your MRs
2. Enable labels — switch to --mode=OnlyLabels to add status labels without merging
3. Go live — when ready, switch to --mode=Run for full automation

See Execution Modes for a full comparison of all available modes.

Docker Compose

For production deployments, use Docker Compose:

services:
  gitlab-auto-merge:
    image: neckarit/gitlab-auto-merge:latest
    container_name: gitlab-auto-merge
    restart: unless-stopped
    ports:
      - "8711:8711"
    environment:
      - DEPLOYMENT_STAGE=Production
      - GITLAB_SERVER_URL=https://gitlab.example.com
      - GITLAB_PROJECT=group/project
      - GITLAB_ACCESS_TOKEN=${GITLAB_ACCESS_TOKEN}
    command:
      - "--mode=Run"

Troubleshooting

Container starts but shows 403 Forbidden in logs: The access token has insufficient permissions. The token must have Maintainer role on the project. Verify with:

curl --header "PRIVATE-TOKEN: <your-token>" \
  https://gitlab.example.com/api/v4/projects/<group>%2F<project>/merge_requests

If this returns 403, the token needs a higher access level.

No merge requests appear: Check docker logs gitlab-auto-merge for errors. In DryRun mode, the service reads MRs but makes no changes. If the project has no open MRs, the output will be empty.

Requirements

• Docker (or any OCI-compatible container runtime)
• GitLab (self-hosted CE/EE or GitLab.com)
• Access token with api scope and Maintainer role — see Access Token