BuildButler GitLab CI Integration

Reports GitLab CI pipeline data (builds, stages, test results, runners) to BuildButler.

Quick Start

1. Add your API key to GitLab CI/CD variables

In your GitLab project: Settings → CI/CD → Variables

| Variable | Value | Protected | Masked | |---|---|---|---| | BUILDBUTLER_API_KEY | Your API key from BuildButler | ✓ | ✓ |

2. Add the BuildButler job to your .gitlab-ci.yml

include:
  - remote: 'https://raw.githubusercontent.com/railflow/buildbutler/main/integrations/gitlab-ci/buildbutler.gitlab-ci.yml'

buildbutler:
  extends: .buildbutler-report

That's it. The job runs in the .post stage so it always executes after your pipeline completes.

Configuration

All configuration is via CI/CD variables:

| Variable | Required | Default | Description | |---|---|---|---| | BUILDBUTLER_API_KEY | Yes | — | Your BuildButler API key | | BUILDBUTLER_API_URL | No | https://api.buildbutler.dev | API endpoint (self-hosted installs) | | TEST_RESULTS_GLOB | No | "" | Glob for JUnit XML files, e.g. build/test-results/**/*.xml | | GITLAB_API_TOKEN | No | — | PAT with read_api scope — enables full runner fleet reporting |

Test Results

To report JUnit XML test results, set TEST_RESULTS_GLOB:

buildbutler:
  extends: .buildbutler-report
  variables:
    TEST_RESULTS_GLOB: "build/test-results/**/*.xml"

Artifacts must be available in the .post stage. Use artifacts: when: always on your test job:

test:
  script: ./gradlew test
  artifacts:
    when: always
    paths:
      - build/test-results/**/*.xml
    reports:
      junit: build/test-results/**/*.xml

Runner Reporting

By default, only the current runner is reported (using CI_RUNNER_DESCRIPTION from the environment — no token needed).

For full runner fleet visibility, add a GitLab PAT with read_api scope:

GITLAB_API_TOKEN = <your-personal-access-token>

What Gets Reported

• Build: pipeline status, duration, branch, commit SHA, trigger source
• Pipeline stages: each CI job name, status, and duration
• Runner: current runner description, tags, and architecture
• Test results: parsed from JUnit XML files (pass/fail/skip counts + individual test cases)

Self-Hosted GitLab

Set CI_SERVER_URL is automatically picked up from the GitLab CI environment. For self-hosted instances, CI_API_V4_URL is also pre-configured by GitLab — no extra setup needed.

Publishing a New Version

cd integrations/gitlab-ci
# bump version in package.json, then:
npm run build
npm publish --access public

Requires npm login as an owner of the @buildbutler org (npm login).

How Deduplication Works

Each pipeline produces a deterministic UUID from CI_PROJECT_PATH + CI_PIPELINE_ID. Re-running the reporter script for the same pipeline upserts the existing record rather than creating a duplicate.