GitLab CI

Send build results, job stages, and test data from GitLab CI to BuildButler using a zero-config group-level webhook or the @buildbutler/ci CLI reporter.

Option 1: Group Level Webhooks

Configure one webhook on your GitLab group and every pipeline across all projects is automatically reported to BuildButler — no per-project .gitlab-ci.yml changes needed.

1. Generate an API key

1. In the BuildButler web app, go to Settings → Add API key. Copy it — you'll need it in the next step.

2. Add the webhook

1. Go to your GitLab group → Settings → Webhooks → Add new webhook
2. Fill in the form:

3. Click Save changes

The secret token is sent with every request in the X-Gitlab-Token HTTP header — this is how BuildButler authenticates your webhook.

3. How it works

• Only terminal pipeline states (success, failed, canceled) are stored — in-progress events are acknowledged and ignored
• Job stages and runner info are extracted directly from the webhook payload — no extra API calls needed
• Trigger a build in GitLab. Within a few seconds it should appear in the Build Results page in the BuildButler web app.

Option 2: CLI Pipeline Reporter

1. Generate an API key

1. In the BuildButler web app, go to Settings → Add API key. Copy it — you'll need it in the next step.

2. Set up CI/CD variables

Add the required credentials at the group level so they're available across all projects.

• Go to your GitLab group Settings → CI/CD
• Expand Variables and add:

2. Generate a GitLab Access Token

• Go to GitLab → Preferences → Access Tokens
• Click Add new token, name it buildbutler
• Grant scope: read_api
• Click Create personal access token and copy it

For group or project-level tokens, navigate to the group/project Settings → Access Tokens instead.

3. Add the reporter job

# .gitlab-ci.yml
report-to-buildbutler:
  stage: .post
  image: node:20-alpine
  when: always
  variables:
    TEST_RESULTS_GLOB: "build/test-results/**/*.xml"   # optional
  script:
    - npx --yes @buildbutler/ci
  allow_failure: true

Key settings:

• stage: .post — runs after all other stages complete
• when: always — runs even if earlier jobs fail
• TEST_RESULTS_GLOB — glob path to JUnit XML test results; remove if you have none
• allow_failure: true — prevents a reporting failure from blocking your pipeline

Option 3: Inject BuildButler

Use a Pipeline execution policy to automatically inject the reporter job into every project pipeline in your group.

1. Policy repository

Create a dedicated repository in your group (e.g. buildbutler-policy) and add .gitlab/ci/buildbutler.yml:

report-to-buildbutler:
  stage: .pipeline
  image: node:20-alpine
  when: always
  variables:
    TEST_RESULTS_GLOB: "build/test-results/**/*.xml"
  script:
    - npx --yes @buildbutler/ci
  allow_failure: true

2. Create the policy

• Go to your group Secure → Policies → New policy → Pipeline execution policy
• Set Actions to Inject with the CI file from your buildbutler-policy repository
• Set Variable option to Deny to prevent projects from overriding the API key
• Click Create policy

3. Link the policy project

• Go to Secure → Security configuration and set the Policy management project to your buildbutler-policy repository

Once configured, every pipeline in the group includes the reporter automatically.

Data mapping

Troubleshooting