GitLab

Fully supported — release MRs, changelog, tagging-on-merge, and brel init all work on GitLab. brel talks to GitLab through its REST API (no extra CLI needed).

Prerequisites

• git available wherever brel runs.
• A GitLab access token with API and repository write access, exposed as BREL_GITLAB_TOKEN. In GitLab CI, add it as a masked CI/CD variable (a project or group access token works well).

Setup

1. Install brel and create a brel.toml at the repository root:

   provider = "gitlab"
   default_branch = "main"
   
   [release_pr.version_updates]
   "package.json" = ["version"]

2. Generate the managed pipeline:

   brel validate
   brel init --yes

   With provider = "gitlab", the default workflow_file is .gitlab-ci.yml — brel manages the whole file (marked # managed-by: brel).

3. Add the BREL_GITLAB_TOKEN masked CI/CD variable in your project settings.

4. Commit and push to main. Every default-branch push pipeline now runs brel release-pr and keeps a release MR up to date.

Note

If your project already has a .gitlab-ci.yml, set workflow_file to a different path and include: it from your main pipeline, or merge the generated jobs by hand — brel init overwrites the file it manages (it prompts before overwriting unless --yes is passed; use --dry-run to preview).

What the generated pipeline does

• Runs on default-branch push pipelines and web-triggered pipelines, in a rust:latest image with GIT_DEPTH: "0" (full history).
• Fails fast with a clear message if BREL_GITLAB_TOKEN is missing.
• Points origin at an oauth2:${BREL_GITLAB_TOKEN}@... URL so brel can push branches and tags.
• Installs a pinned brel with cargo install brel --version <version> --locked, plus the changelog runtime (git-cliff via cargo, or Node for changelogen).
• Runs brel changelog then brel release-pr.

GitLab CI supplies project and commit metadata through predefined CI_* variables (CI_API_V4_URL, CI_PROJECT_ID, CI_SERVER_HOST, …), which brel reads automatically.

Tagging on merge

With [release_pr.tagging] enabled, the pipeline gains a release-tag stage that runs brel tag on default-branch push pipelines. brel uses GitLab’s commit-to-MR API to detect whether the pushed commit merged a managed release MR, and tags it if so. No extra token is needed — BREL_GITLAB_TOKEN covers API calls and tag pushes.

Running locally

Provide the metadata GitLab CI would normally inject:

BREL_GITLAB_TOKEN=... \
CI_API_V4_URL=https://gitlab.com/api/v4 \
CI_PROJECT_ID=123 \
brel release-pr

See Environment Variables for the full list.