Write down how CI works, while it is finally knowable #1077

Merged
jaylouisw merged 3 commits from docs/ci-pipeline into main 2026-11-08 15:55:17 +00:00
Owner

There is no page describing the pipeline. Everything about it — which checks run, what cancels what, why jobs carry timeouts, how to reproduce a failure locally — has lived in commit messages and in the head of whoever last debugged it. That was survivable while the honest answer was "it is broken". Now that it moves, the answers are worth keeping.

docs/CI.md covers:

  • the workflows and their triggers, including why .github/workflows/ is gone (#1059)
  • the five required checks, and what each one actually catches
  • the local commands that reproduce them, and the Node-version trap that makes a suite green locally and red in CI
  • concurrency: pull-request runs cancel, push runs must not, and why the group key is pull_request.number || sha (#1076)
  • the runner's capacity, measured cost, and why 2 and not 3
  • a troubleshooting table for the symptoms people actually hit — "waiting to run", "cancelled immediately", "auto-rebase did nothing"
  • the gaps that remain: main trailing on a busy day, throughput ceiling, scheduled runs competing in the same queue

It is written from the workflows themselves and says so: if the page and the workflow disagree, the workflow is right and the page is a bug.

CONTRIBUTING.md links it from both places a contributor meets CI — the rules list and the review process — because "all checks must pass" without saying which checks is not an instruction.

There is no page describing the pipeline. Everything about it — which checks run, what cancels what, why jobs carry timeouts, how to reproduce a failure locally — has lived in commit messages and in the head of whoever last debugged it. That was survivable while the honest answer was "it is broken". Now that it moves, the answers are worth keeping. `docs/CI.md` covers: - the workflows and their triggers, including why `.github/workflows/` is gone (#1059) - the five required checks, and what each one actually catches - the local commands that reproduce them, and the Node-version trap that makes a suite green locally and red in CI - concurrency: pull-request runs cancel, push runs must not, and why the group key is `pull_request.number || sha` (#1076) - the runner's capacity, measured cost, and why 2 and not 3 - a troubleshooting table for the symptoms people actually hit — "waiting to run", "cancelled immediately", "auto-rebase did nothing" - the gaps that remain: `main` trailing on a busy day, throughput ceiling, scheduled runs competing in the same queue It is written from the workflows themselves and says so: **if the page and the workflow disagree, the workflow is right and the page is a bug.** `CONTRIBUTING.md` links it from both places a contributor meets CI — the rules list and the review process — because "all checks must pass" without saying which checks is not an instruction.
Write down how CI works, while it is finally knowable
Some checks failed
CI / Test (Node 18) (pull_request) Failing after 1m30s
CI / Test (Node 20) (pull_request) Failing after 1m26s
CI / Server smoke test (pull_request) Successful in 25s
CI / Docker build (pull_request) Successful in 10s
CI / Test (Node 22) (pull_request) Failing after 1m26s
8eab33f033
There is no page describing the pipeline. Everything about it - which checks run,
what cancels what, why jobs have timeouts, how to run the same checks locally - has
lived in commit messages and in the heads of whoever last debugged it. That was
survivable while the answers were 'it is broken'; now that it works, the answers
are worth keeping.

docs/CI.md covers the three workflows, the five required checks and what each one
actually catches, the local commands that reproduce them, why pull-request runs
cancel and push runs must not, the runner's capacity and what it costs, a
troubleshooting table, and the gaps that remain.

Written from the workflows themselves, and it says so: if the two disagree, the
workflow is right and the page is a bug.

CONTRIBUTING.md links it from both places a contributor meets CI - the rules list
and the review process - because 'all checks must pass' without saying which
checks is not an instruction.
jaylouisw scheduled this pull request to auto merge when all checks succeed 2026-11-08 15:21:57 +00:00
jaylouisw force-pushed docs/ci-pipeline from 8eab33f033
Some checks failed
CI / Test (Node 18) (pull_request) Failing after 1m30s
CI / Test (Node 20) (pull_request) Failing after 1m26s
CI / Server smoke test (pull_request) Successful in 25s
CI / Docker build (pull_request) Successful in 10s
CI / Test (Node 22) (pull_request) Failing after 1m26s
to c5535f4929
Some checks failed
CI / Test (Node 18) (pull_request) Failing after 1m42s
CI / Test (Node 20) (pull_request) Failing after 1m35s
CI / Server smoke test (pull_request) Successful in 27s
CI / Docker build (pull_request) Successful in 10s
CI / Test (Node 22) (pull_request) Failing after 1m29s
2026-11-08 15:26:25 +00:00
Compare
jaylouisw scheduled this pull request to auto merge when all checks succeed 2026-11-08 15:31:03 +00:00
Author
Owner

Corrected the runner table after a longer sample: ~50 s mean job duration at capacity 1, ~63 s at capacity 2 — the second slot costs about a quarter of a job, so the real gain is ~1.6x, not 2x. The page now says that, and says to watch memory rather than CPU next time.

Corrected the runner table after a longer sample: ~50 s mean job duration at capacity 1, ~63 s at capacity 2 — the second slot costs about a quarter of a job, so the real gain is ~1.6x, not 2x. The page now says that, and says to watch memory rather than CPU next time.
Correct the capacity numbers before this lands wrong
Some checks failed
CI / Test (Node 18) (pull_request) Failing after 1m37s
CI / Test (Node 20) (pull_request) Failing after 1m28s
CI / Server smoke test (pull_request) Successful in 27s
CI / Docker build (pull_request) Successful in 11s
CI / Test (Node 22) (pull_request) Failing after 1m30s
83e2247716
The page claimed the second runner slot was free - 'mean job duration is about 50
seconds and did not change between the two'. A longer sample says otherwise: ~50 s at
capacity 1, ~63 s at capacity 2, because two jobs compete for the same disk and the
same cores. Two slots are still worth having, but by about 1.6x rather than 2x.

Better to write the measured number than the flattering one, particularly in a page
that tells the next person what raising capacity will buy them.
jaylouisw force-pushed docs/ci-pipeline from 83e2247716
Some checks failed
CI / Test (Node 18) (pull_request) Failing after 1m37s
CI / Test (Node 20) (pull_request) Failing after 1m28s
CI / Server smoke test (pull_request) Successful in 27s
CI / Docker build (pull_request) Successful in 11s
CI / Test (Node 22) (pull_request) Failing after 1m30s
to 26633dc39b
All checks were successful
CI / Test (Node 18) (pull_request) Successful in 1m38s
CI / Test (Node 20) (pull_request) Successful in 1m30s
CI / Server smoke test (pull_request) Successful in 25s
CI / Docker build (pull_request) Successful in 43s
CI / Test (Node 22) (pull_request) Successful in 1m28s
2026-11-08 15:51:00 +00:00
Compare
jaylouisw scheduled this pull request to auto merge when all checks succeed 2026-11-08 15:54:34 +00:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
jaylouisw/packetforge!1077
No description provided.