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
- Run
bucker ci doctor --jsonin the repository root, after the tests have written their reports. - Read the
checksarray. Each finding hasid,status,evidenceandfix. - For each
failorwarnwhose fix is a file in the repository, propose the change as a pull request. - For each whose fix names a person (consent, ingest switch, branch protection), say so in the pull request and stop.
- 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 |