Skip to content

docs: CLAUDE.md's CI table omits six jobs, including the one that gates CI's own decision logic #2026

Description

@jhgaylor

CLAUDE.md's CI pipeline table documents 12 of the 19 jobs in
.github/workflows/ci.yml. #2020 rebuilt the table after #1413 split
sdk-clients, but deliberately kept scope to the rows that had gone wrong
rather than adding the ones that were never there. These omissions predate it.

Measured on 97bcf1a6:

Job id Check name a red build shows
workflow-checks CI policy and alert tests
already-tested Skip the re-run when a PR already tested this exact tree
core-distribution Core distribution boots without the extensions
compose-fresh-clone Compose fresh-clone check
compose-pinned-image-boot Compose boots the pinned image
docs Docs

(coverage also has no row of its own, but the test row describes it, so it
is not really undocumented.)

Why this matters, and which one to do first

The table's stated purpose is in the sentence above it: "the job name in a red
build tells you which toolchain to go and look at." That promise fails for any
job not in the table.

workflow-checks is the one worth adding first. It runs
python3 -m unittest discover -s scripts/ci, which is the suite that gates the
CI decision logic itself — gate.py, sdk_changes.py, require-checks.py and
their tests. Someone who breaks one of those sees a failing check called
CI policy and alert tests, a name that appears nowhere in the table, and the
job also runs scripts/conflict-markers.py and the alert-fixture evaluation
(#1927, #1939), so the name does not obviously point at scripts/ci/ either.

already-tested is the second most useful, because a reader who sees it
skipped needs to know that is normal on a pull_request and that the probe
only runs on push and merge_group.

Suggested shape

One row each, in the same style as the existing rows: what it runs, plus the
one fact a reader cannot get from the workflow. For workflow-checks that is
"the suite that gates CI's own decision logic"; for already-tested, which
events it runs on and what a skip means.

Related: #1413 (the split), #2020 (the table rebuild that set this scope aside).

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:docsDocumentation content, structure and accuracy.area:testingTests, test infrastructure and CI verification.good first issueSuitable for a first contribution, with clear scope and guidance.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions