Skip to content
bucker

CI setup runbook

This page is for a person or a coding agent connecting a repository's CI to Bucker. It is written to be read by a program: every table cell is filled, and a support matrix says yes, no or n/a, never nothing. A docs test fails on an empty cell in this file.

What you may change

Thing An agent may change it How
Files in the repository (workflow YAML, test-runner config) yes a pull request that a person merges
Merging the pull request no a person
Branch protection and required checks no a repository admin
Bucker project settings, including turning CI ingest on no an organization admin, in the dashboard
The GitHub App's permissions (consent) no an organization admin
Tokens and the DSN no a person creates them and stores them as CI secrets or variables

Doctor reads; it never writes. It makes GET requests only and prints a token's kind and scopes, never the token.

The loop

  1. Run bucker ci doctor --json in the repository root, after the tests have written their reports.
  2. Read the checks array. Each finding has id, status, evidence and fix.
  3. For each fail or warn whose fix is a file in the repository, propose the change as a pull request.
  4. For each whose fix names a person (consent, ingest switch, branch protection), say so in the pull request and stop.
  5. After a person merges, run doctor again.

Exit codes

Exit code Meaning What to do
0 every check passed or warned warnings are advice, not blockers
1 at least one check failed fix the failed checks; a failure beats a could-not-check
2 nothing failed but a check that matters could not be made retry; the server may be older than the CLI, or the token may not reach the project

A not_checked finding carries blocking. Only a blocking one moves the exit code to 2. Branch protection that needs admin consent to read is not_checked with blocking: false.

The checks

Check id Fails when Warns when Needs the server
action_version no workflow runs a bucker action or @bucker/cli a reference is a branch, a major tag or an unversioned CLI no
token no token, a 401, or release:write missing the token is personal or an agent's, not an org CI token yes
dsn no DSN, or one that does not parse never no
connectivity the API or the ingest host is unreachable or answers 5xx never no
github_consent no connection, or checks:write or actions:read not granted never yes
webhook_deliveries no delivery at all in 24 hours one of workflow_job, check_run, merge_group, deployment_status is missing yes
junit_files no JUnit file, or none usable some unusable, or older than 71 hours no
coverage_files never no coverage file found no
identity_stability never more than 20% of test identities appear in only one of the last 30 runs yes
traceparent never TRACEPARENT is absent or malformed no
merge_queue never merge_group events arrive and no workflow triggers on them, or neither exists yes
gate_setup never the gate check is not required, or production's only protection is Bucker's yes

Uploading results

bucker ci upload "reports/*.xml" --dsn "$BUCKER_DSN"

The command reads the commit, branch, run id, attempt, workflow, job and pull request from the CI system's own variables, and TRACEPARENT and BAGGAGE (cicd.pipeline.run.id) when the pipeline exports them. A flag wins over the environment. It sends each file to POST /api/:projectId/ci/reports on the DSN's ingest host with the DSN public key, and exits 0 only when every file was accepted.

Flag Meaning Default
--format junit or coverage junit
--sha full commit id the CI variable, then git rev-parse HEAD
--branch branch name the CI variable
--run-id the CI system's run id the CI variable, then BAGGAGE
--attempt attempt number, 1 to 100 the CI variable, else 1
--workflow workflow name the CI variable
--job job name the CI variable
--config a suffix for test identity: operating system, runtime, matrix key none
--pr comma-separated pull request numbers the CI variable
--dry-run find the files and print what would be sent off

CI systems read

CI system Commit Run id Job Pull request
GitHub Actions yes yes yes yes
GitLab CI yes yes yes yes
CircleCI yes yes yes yes
Buildkite yes yes yes yes
Jenkins yes yes yes no
Anything else no no no no

On a system marked no, pass the flag. The commit always falls back to the git checkout.

Formats the door accepts

Format Accepted today Notes
JUnit XML yes surefire reruns and flaky markers are understood; a DOCTYPE is refused
Coverage no the door answers with a reason until coverage ingest ships
TAP no convert to JUnit
TRX no convert to JUnit

Limits: 8 MiB per file. A refused file prints the door's reason (ci_ingest_disabled, report_too_large, report_format_unsupported, and the parser's own). A 429 or 5xx is retried three times; a refusal is never retried.

The GitHub Actions step

- uses: bucker/release-action/ci-upload@<full commit sha>
  if: always()
  with:
    dsn: ${{ vars.BUCKER_DSN }}
    files: reports/*.xml

Pin the action to a full commit SHA. The cli-version input is an exact version.

What doctor reads

Doctor reads two routes through the control plane with the caller's token. A server that does not serve them yields not_checked findings and exit 2, not a failure.

Route Used by
GET /orgs/:org/projects/:project/ci/setup token scopes, github_consent, webhook_deliveries, merge_queue, gate_setup
GET /orgs/:org/projects/:project/ci/runs?limit=30 identity_stability