ci-annotate

Overview ¶

Command ci-annotate says why a CI step failed, where a reader without a token can see it: in the annotations of the job's check run.

A GitHub Actions job log can only be read with admin rights on the repository — GET /repos/{owner}/{repo}/actions/jobs/{id}/logs answers 403 without them — while a check run's annotations come back from the public API to anyone (GET /repos/{owner}/{repo}/check-runs/{id}/annotations; a job's id is its check run's). A failed job's only annotation used to be "Process completed with exit code 1." (Task 20444).

This reads what go test, go build and go vet print — the plain text a tee'd step writes, or go test -json — and emits one GitHub workflow command per cause: a failing test, a panic, a data race, a test binary that outlived its -timeout, a package that did not build, vet or set up. GitHub keeps the first ten annotations of each level a step emits and fifty a job, so the causes are ranked — the first failed step first, and within it what stopped a package from running at all before what failed inside one — and whatever does not fit is folded into the last annotation that does. Everything, unabridged, goes to the step summary.

go run ./scripts/ci-annotate [flags] FILE...   annotate go output (- is stdin)
go run ./scripts/ci-annotate -steps DIR        annotate a job's failed steps

The second form is what each CI job's last step runs, through scripts/ci-step.sh --why: DIR holds every step's recorded output and exit status, and a failed step whose output names no Go failure is annotated with its last lines instead.

It never decides a verdict: it exits 0 whatever it finds, and 2 only for a command line it cannot use.