GitHub Actions

Send build results, job stages, and test data from GitHub Actions to BuildButler using the @buildbutler/ci CLI or a zero-config org-level webhook.

Option 1: Org-level webhook

Configure one webhook at the GitHub organization level and every repository's workflow runs are automatically reported to BuildButler — no per-repo .github/workflows 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 GitHub organization → Settings → Webhooks → Add webhook
2. Fill in the form:

3. Click Add webhook

GitHub will immediately send a ping event — BuildButler will respond with 200 OK.

3. How it works

• BuildButler only processes workflow_run events with action: completed — in-progress events are acknowledged and ignored
• Each completed workflow run is stored as a build; concurrent runs of the same workflow are deduped by run ID

- uses: actions/upload-artifact@v4
  if: always()
  with:
    name: test-results
    path: build/test-results/combined/TEST-combined.xml

Option 2: CLI Workflow Reporter

If webhooks are not available, add a reporter step in your workflow that runs after all jobs complete.

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 reporter step

  - name: Report to BuildButler
    if: always()   # run even when previous steps fail
    env:
      BUILDBUTLER_API_KEY: ${{ secrets.BUILDBUTLER_API_KEY }}
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      GITHUB_JOB_STATUS: ${{ job.status }}          # ← required for correct status
      TEST_RESULTS_GLOB: "**/test-results/**/*.xml"
    run: npx @buildbutler/ci

Key settings:

• if: always() — runs even when earlier steps fail so BuildButler always receives data
• GITHUB_JOB_STATUS — passes the final job result; required to distinguish pass from fail
• TEST_RESULTS_GLOB — glob path to JUnit XML test results; remove if you have none
• GITHUB_TOKEN — injected automatically by GitHub Actions and used by the reporter to fetch per-job stage details — no extra configuration needed

Data mapping

Troubleshooting