CLI Reporter

The @buildbutler/ci npm package — report build results, stages, and test data from any CI system.

The @buildbutler/ci CLI reporter is an npm package that runs inside your CI pipeline after a build completes. It auto-detects the CI environment, collects build results, stage details, and test data, then sends everything to BuildButler in one step.

Use it when webhooks are unavailable or when you need richer data (JUnit test results, per-job stage details) that webhooks don't provide.

Installation

No installation required — run it directly with npx:

npx @buildbutler/ci

Or install globally:

npm install -g @buildbutler/ci
buildbutler-ci

Or add it as a dev dependency:

npm install --save-dev @buildbutler/ci

Configuration

The reporter is configured via environment variables.

Variable	Required	Description
`BUILDBUTLER_API_KEY`	Yes	Your BuildButler API key — found in Settings → API Keys
`BUILDBUTLER_API_URL`	No	Override the API endpoint. Defaults to `https://api.buildbutler.dev`. Set this for self-hosted deployments
`TEST_RESULTS_GLOB`	No	Glob pattern to JUnit XML test result files, e.g. `/test-results//*.xml`

CI-specific tokens (for fetching stage details) are listed per-system below.

Usage by CI system

GitHub Actions

Add a reporter step at the end of your job. The GITHUB_TOKEN is automatically available and is used to fetch per-job stage details.

- name: Report to BuildButler
  if: always()
  env:
    BUILDBUTLER_API_KEY: ${{ secrets.BUILDBUTLER_API_KEY }}
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    GITHUB_JOB_STATUS: ${{ job.status }}
    TEST_RESULTS_GLOB: "**/test-results/**/*.xml"
  run: npx @buildbutler/ci

Variable	Notes
`if: always()`	Ensures the step runs even when earlier steps fail
`GITHUB_JOB_STATUS`	Required — passes the final job result to the reporter
`GITHUB_TOKEN`	Injected automatically by GitHub Actions — used to fetch per-job stage details
`TEST_RESULTS_GLOB`	Remove if you have no JUnit results

GitLab CI

Add a reporter job in the .post stage so it runs after all other stages complete.

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

Variable	Notes
`stage: .post`	Runs after all other stages
`when: always`	Runs even if earlier jobs fail
`GITLAB_API_TOKEN`	GitLab access token with `read_api` scope — used to fetch stage details
`allow_failure: true`	Prevents a reporting failure from blocking your pipeline

Set BUILDBUTLER_API_KEY and GITLAB_API_TOKEN as group-level CI/CD variables so they're available across all projects.

Buildkite

Add a reporter step at the end of your pipeline.

- label: "Report to BuildButler"
  command: npx @buildbutler/ci
  if: always()
  env:
    BUILDBUTLER_API_KEY: "your-api-key"
    BUILDKITE_API_TOKEN: "your-buildkite-token"
    TEST_RESULTS_GLOB: "**/test-results/**/*.xml"

Variable	Notes
`if: always()`	Runs even when earlier steps fail
`BUILDKITE_API_TOKEN`	Buildkite API token with read scopes for pipelines, builds, logs, artifacts, and agents — used to fetch per-step stage details
`TEST_RESULTS_GLOB`	Remove if you have no JUnit results

Azure DevOps

Add a reporter step at the end of your pipeline job. Use a script task that always runs so it executes even when earlier steps fail.

- task: NodeTool@0
  inputs:
    versionSpec: "20.x"
  displayName: "Use Node.js 20"
 
- script: npx @buildbutler/ci
  displayName: "Report to BuildButler"
  condition: always()
  env:
    BUILDBUTLER_API_KEY: $(BUILDBUTLER_API_KEY)
    AZURE_DEVOPS_TOKEN: $(AZURE_DEVOPS_TOKEN)
    TEST_RESULTS_GLOB: "**/test-results/**/*.xml"

Variable	Notes
`condition: always()`	Runs even when earlier steps fail
`AZURE_DEVOPS_TOKEN`	Azure DevOps personal access token with Build (read) scope — used to fetch per-step stage details
`TEST_RESULTS_GLOB`	Remove if you have no JUnit results

Set BUILDBUTLER_API_KEY and AZURE_DEVOPS_TOKEN as pipeline variables (marked secret) so they're available across all pipelines.

Self-hosted deployments

Point the reporter at your own BuildButler server by setting BUILDBUTLER_API_URL:

BUILDBUTLER_API_URL=http://your-server:3000 npx @buildbutler/ci

Or as an environment variable in your pipeline YAML alongside BUILDBUTLER_API_KEY.

On this page