# 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

```bash
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

```yaml
- 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` |
