Access Token

Auto Merge requires a GitLab access token with api scope to interact with merge requests, pipelines, and labels.

Create a Token

Option A: Project Access Token (recommended)

1. Go to Settings > Access tokens in the GitLab project
2. Create a token with Maintainer role and api scope
3. GitLab creates a bot user automatically

Option B: Personal Access Token

1. Create a dedicated bot user in GitLab
2. Grant the bot Maintainer access to the project
3. Generate a Personal Access Token with api scope under the bot user’s account

The token must have the Maintainer role. Lower roles (Guest, Reporter, Developer) result in 403 Forbidden errors.

Verify the Token

Before configuring Auto Merge, verify the token can access the project:

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

A successful response returns a JSON array (possibly empty). A 403 Forbidden response means the token has insufficient permissions.

Configuration

Pass the token via the GITLAB_ACCESS_TOKEN environment variable:

environment:
  - GITLAB_ACCESS_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx

Caution

Store the token securely. Use Docker secrets or a secrets manager in production — avoid hardcoding tokens in configuration files.

Bot User Avatar

Auto Merge automatically sets the bot user’s avatar at startup, making it easy to identify automated actions in GitLab. This is skipped in DryRun mode.

Required Permissions

Permission	Used For
api scope	Full API access (MRs, pipelines, labels, notes)
Maintainer role	Merging MRs, rebasing, managing labels