Gitlab

Connect your GitLab instance (SaaS or self-managed) to BuildButler to import pipeline runs, job results, and test data.

Set up CI/CD variables

To use BuildButler in your GitLab pipelines, add the required credentials as CI/CD variables at the group level so they're available across all projects.

• Go to your GitLab group Settings → CI/CD
• Expand the Variables section
• Click Add variable and add the following:

Set both variables as Expanded so they can be referenced in scripts. Mark them as Masked to prevent exposure in job logs.

For the Default role to use pipeline variables setting, Developer or higher is recommended so pipeline jobs can access these variables.

Generate a GitLab Access Token

BuildButler uses the GitLab API to pull logs and metrics. Create a GitLab access token with repo access and store it at the group level CI/CD variables so that all projects have access to the variable.

• Go to GitLab → Preferences → Access Tokens
• Click Add new token
• Give it a name like buildbutler
• Set the expiration date as needed
• Select the following scopes:
  • read_api — access pipeline and job data
• Click Create personal access token and copy it

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

Generate BuildButler API Key

In BuildButler, go to Settings → API Keys and create a new API key.

Store the key as BUILDBUTLER_API_KEY in your group CI/CD variables. Once set at the group level, it will be inherited by all projects automatically.

Add BuildButler Reporter

Add a report-to-buildbutler job to your .gitlab-ci.yml to send pipeline and test results to BuildButler after each run:

report-to-buildbutler:
  stage: report
  image: node:20-alpine
  when: always
  variables:
    TEST_RESULTS_GLOB: "build/test-results/combined/TEST-combined.xml"
  script:
    - npx --yes @buildbutler/[email protected]
  needs:
    - job: unit-tests
      artifacts: true
  allow_failure: true

Key settings:

• when: always — runs even if earlier jobs fail, so BuildButler always receives data
• TEST_RESULTS_GLOB — glob path to your JUnit XML test results; adjust to match your build output
• needs — ensures test artifacts are available; update the job name to match your test job
• allow_failure: true — prevents a reporting failure from blocking your pipeline
• @buildbutler/[email protected] — pin to a specific version for reproducibility

Make sure BUILDBUTLER_API_KEY and GITLAB_API_TOKEN are set as group CI/CD variables before running the pipeline.

Inject BuildButler

Use a Pipeline execution policy to automatically inject the report-to-buildbutler job into every project pipeline in your group — no changes needed in individual repositories.

1. Policy Repository

Create a dedicated repository in your group (e.g. buildbutler-policy) and add a file at .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/[email protected]
  allow_failure: true

Using stage: .pipeline ensures the job runs in a system-managed stage that does not interfere with project-defined stages.

2. Pipeline Execution Policy

• Go to your GitLab group Secure → Policies
• Click New policy and select Pipeline execution policy
• Fill in the form:
  • Name — e.g. BuildButler Reporting
  • Policy status — Enabled
  • Actions — set to Inject into the .gitlab-ci.yml with the pipeline execution file from your buildbutler-policy repository
  • File path — link to the CI file in your policy repo (e.g. .gitlab/ci/buildbutler.yml)
  • File reference — default branch
  • Add job name suffix — On conflict (avoids name collisions with project jobs)
  • Variable option — set to Deny to prevent projects from overriding the variables used by the policy
• Click Create policy

The equivalent YAML (visible in .yaml mode) looks like:

pipeline_execution_policy:
  - name: BuildButler Reporting
    description: Inject BuildButler reporter into all project pipelines
    enabled: true
    pipeline_config_strategy: inject_policy
    content:
      include:
        - project: your-group/buildbutler-policy
    skip_ci:
      allowed: false
    variables_override:
      allowed: false
      exceptions: []

Setting variables_override.allowed: false ensures projects cannot override BUILDBUTLER_API_KEY or GITLAB_API_TOKEN through their own CI variables.

3. Link the policy project

• Go to Secure → Security configuration in your group
• Under Pipeline execution policy, set the Policy management project to your buildbutler-policy repository

Once configured, every pipeline in the group will automatically include the report-to-buildbutler job without any per-project .gitlab-ci.yml changes. Credentials are inherited from group CI/CD variables.

Data mapping

GitLab concepts map to BuildButler as follows:

Troubleshooting