Skip to content
Auto Merge for GitLabAuto Merge for GitLab

Environment Variables

Required

Section titled “Required”
Variable Description
GITLAB_SERVER_URL GitLab instance URL (e.g., https://gitlab.com)
GITLAB_PROJECT Project path (e.g., mygroup/myproject)
GITLAB_ACCESS_TOKEN GitLab personal access token with api scope

Optional

Section titled “Optional”
Variable Description Default
GITLAB_WEBHOOK_SIGNING_TOKEN Signing token (whsec_…) of the GitLab webhook. Unset: every webhook delivery gets 401, Auto Merge polls —
CA_CERT_BASE64 Base64-encoded CA certificate (PEM). Takes precedence over CA_CERT_PATH —
CA_CERT_PATH Path to custom CA certificate file (PEM) —
EXECUTION_ENVIRONMENT LocalDev, Standalone, Docker, CI Docker (no need to set when running in Docker)
DEPLOYMENT_STAGE Development, Staging, Production —
SERVICE_HOST Service host identifier —
DIAGNOSTICS_ENABLED Write the diagnostics bundle (false switches it off) true
DIAGNOSTICS_DIRECTORY Directory of the diagnostics bundle /var/lib/neckar/diagnostics
DIAGNOSTICS_RETENTION Files older than this are deleted, e.g. 7d, 36h 7d
DIAGNOSTICS_MAX_SIZE Upper bound of the directory; the oldest files are deleted above it, e.g. 1GiB, 500MiB 1GiB

Diagnostics Bundle

Section titled “Diagnostics Bundle”

Auto-Merge writes every cycle and every scheduler event as one JSON line into DIAGNOSTICS_DIRECTORY: one file per UTC hour under cycles/, one file per UTC day under scheduler-events/, finished files compressed with xz. Each cycle line holds, per open merge request, the state, the desire, the plan with its hold reason, and every executed command with its result; it holds neither the access token nor description texts.

Mount a volume on /var/lib/neckar to keep the files across container re-creation:

services:
  gitlab-auto-merge:
    image: neckarit/gitlab-auto-merge:latest
    volumes:
      - auto-merge-state:/var/lib/neckar


volumes:
  auto-merge-state:

Collect everything support needs in one archive, on the Docker host of the container:

Terminal window
curl -fsSL https://auto-merge.dev/auto-merge-diagnostics.sh | bash

The script finds the Auto-Merge container, copies the diagnostics directory, adds the container log, docker inspect and the answers of the status endpoints, replaces the value of every secret environment variable by <redacted>, and writes auto-merge-diagnostics-<timestamp>.tar.gz into the current directory. --container, --since and --output override its defaults (bash -s -- --container gitlab-auto-merge).

Export a time range as tar.xz with manifest.json:

Terminal window
curl -o auto-merge-diagnostics.tar.xz \
  "http://localhost:8711/api/auto-merge/diagnostics/bundle?from=2026-09-24T08:00:00Z&to=2026-09-24T14:00:00Z"

Without HTTP access, copy the directory out of the container:

Terminal window
docker cp gitlab-auto-merge:/var/lib/neckar/diagnostics ./auto-merge-diagnostics

Read a finished hour with xzcat cycles/2026-09-24/12.jsonl.xz | jq. GET /api/auto-merge/diagnostics/status returns writeFailures and droppedCycles.

Example

Section titled “Example”
Terminal window
docker run -d \
  --name gitlab-auto-merge \
  --restart unless-stopped \
  -p 8711:10200 \
  -e DEPLOYMENT_STAGE=Production \
  -e GITLAB_SERVER_URL=https://gitlab.example.com \
  -e GITLAB_PROJECT=mygroup/myproject \
  -e GITLAB_ACCESS_TOKEN=glpat-xxxx \
  neckarit/gitlab-auto-merge:latest \
  --mode=Run