CI/CD: the workflows
The repository's automation is six GitHub Actions workflows, and none of their files is written by hand. Each is a typed value in commons/libraries/src/workflows/definitions.ts; bun commons/libraries/src/generate-workflows.ts writes .github/workflows/<name>.auto.yml from it (--check compares and writes nothing), and repoctl sync runs the same generator. To change a workflow, edit the definition and regenerate, never the .auto.yml file (commons 0030-generated-workflows). The pinned Bun, which every workflow uses, is the composite action .github/actions/bun.
How a change is checked
ciplans from what a push or pull request changed (commons/libraries/src/plan.ts, the same affected-libraries code asdev:check), then runsverifyand the tests on Node 26 for the libraries that change affects, on Linux; and on Windows and macOS only for the libraries whose record inLIBRARY_CInames them. Its jobciis the one result to require.testsruns the tests of the repository's own files (tests/) on Bun and on Node 26, and checks the generated files and the rules that are not a compiler or a test (repoctl checkcovers the same ground by hand).conformanceruns what a library's tests cannot alone: the OTLP of the telemetry library against the pinned OpenTelemetry Collector, and a program compiled into one binary on each system.- The documentation site is checked inside
site: the generator's tests andifc-docs checkgate a pull request and nothing else (the site's own page of checks).
Findings, never failures
A run is red only for a fault of the pipeline's own scripting or configuration (the closed list of red causes, below on this page). Everything a module says (a failing test, a type error, a warning, a crashed command) is a finding: each step of a workflow that runs a module's command goes through one wrapper that keeps what the command printed, reads it into typed findings and ends green. The job that gathers a workflow's findings is the one result to require; it is red only where a cell that ran left no findings file. Each run is kept on the branch findings-history, and the people who review quality and risk read the findings, their history and the accepted risks on the build findings page.
How the evidence and the site are made
evidenceruns by the hour and by hand, never on a push: the tests of every library and of the repository's owntests/(one job for each, kept as a CTRF report with line coverage), a nightly job that runs mutation testing on a list of libraries (MUTATION_LIBRARIESin the definitions), and acollectjob that gathers the reports into one artifact. A failed test is what the site is to show, so these jobs do not fail the workflow for what they find.sitebuilds on every push tomainfrom the newest evidence artifact and publishes to GitHub Pages whatever failed, with an emergency page made from the evidence alone where even the build failed. It also runs after the other workflows complete, so the page of runs is fresh. What it shows is in Quality, and the DORA measures are taken from its runs.
How a release is made
releaseis run by hand frommainafterrepoctl release applyhas been committed and pushed: see the release.
The workflows
Read from the typed definitions the workflow files are made from, so this table is the workflows as they are: the files are generated and are never edited by hand.
| Workflow | File | Starts on | Jobs | What it is for |
|---|---|---|---|---|
| ci | .github/workflows/ci.auto.yml | push (paths of commons), pull request, by hand, schedule 17 3 * * * (UTC) | plan, verify, systems, ci, keep-findings | The libraries of commons (commons 0001-libraries FR-012, 0027-commons-libraries FR-019 to FR-022): one workflow for every library. |
| conformance | .github/workflows/conformance.auto.yml | push (paths of commons), pull request | otel-conformance, compile, findings, keep-findings | What a library's own tests cannot run alone: the OTLP of the telemetry library sent to the pinned OpenTelemetry Collector and read back from its file exporter (telemetry 0001-telemetry FR-020), and a program built into one binary by the pinned Bun on each system, then run, and Windows built from Linux (system 0001-system FR-013). |
| evidence | .github/workflows/evidence.auto.yml | by hand, schedule 17 * * * * (UTC), schedule 43 3 * * * (UTC) | plan, tests, repository, mutation, collect, findings, keep-findings | The evidence of quality for the documentation site (commons 0011-documentation FR-042): the tests of every library and of the repository's own `tests/`, one job for each, each kept as a CTRF report with a status file that says why there is none (the packages could not be installed, there is no suite, the run timed out). |
| release | .github/workflows/release.auto.yml | by hand | plan, build, publish, findings, keep-findings | The release of the libraries (commons 0001-libraries FR-014, FR-015): by hand, from main, after `bun run release apply` (commons/libraries/src/releasing.ts) has written the versions and the record `commons/generated/release.auto.json` and they are pushed. |
| site | .github/workflows/site.auto.yml | push (paths of commons), pull request, by hand, schedule 41 4 * * * (UTC), after evidence, ci, release, tests, conformance | check, site, publish, findings, keep-findings | The documentation site of commons (commons 0011-documentation FR-020, FR-041, FR-042): made by commons/docs, from commons' TypeScript and spec kit and, beside them, the evidence of quality. |
| tests | .github/workflows/tests.auto.yml | push to main, pull request | check, tests, workflows, windows, robot, findings, keep-findings | The tests of the repository's own files (`tests/`: the one-command installers of agora, commons' packaging tools and specification checker, the layout of the repository), on IFC TypeScript: Bun, the default runtime, and Node 26, the backup. |
The build policy
Read from the typed values the workflows are made from (commons 0038-build-policy), so that this page and the pipeline cannot disagree. A run ends red only for a cause of this list; everything else a module says is a finding, shown on the build findings page.
| Red cause | Why it is one |
|---|---|
workflow-invalid | a workflow or action file that is not what the model makes, or that GitHub's schema refuses, is the pipeline's own configuration: no module wrote it and no module can fix it |
wrapper-misused | the step wrapper called with an unknown step, no command or an unreadable policy is the pipeline's own scripting: it can say nothing about a module |
plan-unavailable | when the job that plans the matrix cannot make it, no cell can run and no report can be made: the pipeline cannot start |
reports-not-produced | when a cell ran and left no findings file, the pipeline has lost what it exists to keep, and nothing it says afterwards could be trusted |
The release publishes regardless of open findings until 2027-01-31 (the policy "publish-regardless"); after that day the run does not proceed and carries the finding owner-review-due, so that nothing continues silently.
What each step is
189 steps in all: 34 red-cause, 58 finding, 4 gate, 93 plumbing. A step of findings runs through one wrapper and ends green; plumbing never decides; only a red cause or a gate may end a job red.
| Workflow | Job | Step | Is | Detail |
|---|---|---|---|---|
| ci.auto.yml | plan | actions/checkout@v4 | red-cause | plan-unavailable |
| ci.auto.yml | plan | ./.github/actions/bun | red-cause | plan-unavailable |
| ci.auto.yml | plan | The packages the plan reads, from the root's bun.lock | red-cause | plan-unavailable |
| ci.auto.yml | plan | The libraries, linked by name before any of them is imported (the root's packages are old copies from npm) | red-cause | plan-unavailable |
| ci.auto.yml | plan | The libraries this change affects, and the systems each runs on | red-cause | plan-unavailable |
| ci.auto.yml | verify | actions/checkout@v4 | plumbing | |
| ci.auto.yml | verify | ./.github/actions/bun | plumbing | |
| ci.auto.yml | verify | The development tools, from bun.lock (the libraries it imports are linked) | finding | install, 6 min |
| ci.auto.yml | verify | verify (its packing is checked where the exports changed, and by the release) | finding | verify, 16 min |
| ci.auto.yml | verify | After verify | finding | verify, 16 min |
| ci.auto.yml | verify | The tests on Node 26 | finding | bun-test, 16 min |
| ci.auto.yml | verify | The findings of this job, kept for the job that gathers them | plumbing | |
| ci.auto.yml | systems | actions/checkout@v4 | plumbing | |
| ci.auto.yml | systems | ./.github/actions/bun | plumbing | |
| ci.auto.yml | systems | The development tools, from bun.lock (the libraries it imports are linked) | finding | install, 6 min |
| ci.auto.yml | systems | verify (its packing is checked where the exports changed, and by the release) | finding | verify, 16 min |
| ci.auto.yml | systems | After verify | finding | verify, 16 min |
| ci.auto.yml | systems | The tests on Node 26 | finding | bun-test, 16 min |
| ci.auto.yml | systems | The findings of this job, kept for the job that gathers them | plumbing | |
| ci.auto.yml | ci | actions/checkout@v4 | red-cause | reports-not-produced |
| ci.auto.yml | ci | ./.github/actions/bun | red-cause | reports-not-produced |
| ci.auto.yml | ci | The findings every job kept | plumbing | |
| ci.auto.yml | ci | The findings, merged; the pipeline is sound where every cell that ran left its file (ci/collect.ts) | red-cause | reports-not-produced |
| ci.auto.yml | ci | The merged findings, kept for the site | plumbing | |
| ci.auto.yml | keep-findings | actions/checkout@v4 | plumbing | |
| ci.auto.yml | keep-findings | ./.github/actions/bun | plumbing | |
| ci.auto.yml | keep-findings | The merged findings of this workflow | plumbing | |
| ci.auto.yml | keep-findings | The findings added to the history branch (the only writer) | plumbing | |
| conformance.auto.yml | otel-conformance | actions/checkout@v4 | plumbing | |
| conformance.auto.yml | otel-conformance | ./.github/actions/bun | plumbing | |
| conformance.auto.yml | otel-conformance | The development tools, from bun.lock | finding | install, 3 min |
| conformance.auto.yml | otel-conformance | The OpenTelemetry Collector, verified against commons' pins | finding | exit-status, 8 min |
| conformance.auto.yml | otel-conformance | The conformance test, on Bun and on Node | finding | bun-test, 8 min |
| conformance.auto.yml | otel-conformance | The findings of this job, kept for the job that gathers them | plumbing | |
| conformance.auto.yml | compile | actions/checkout@v4 | plumbing | |
| conformance.auto.yml | compile | ./.github/actions/bun | plumbing | |
| conformance.auto.yml | compile | The development tools, from bun.lock | finding | install, 3 min |
| conformance.auto.yml | compile | Built for this computer, with an embedded file, and run | finding | bun-test, 8 min |
| conformance.auto.yml | compile | Built for Windows from Linux, by the pinned Bun alone | finding | exit-status, 8 min |
| conformance.auto.yml | compile | The findings of this job, kept for the job that gathers them | plumbing | |
| conformance.auto.yml | findings | actions/checkout@v4 | red-cause | reports-not-produced |
| conformance.auto.yml | findings | ./.github/actions/bun | red-cause | reports-not-produced |
| conformance.auto.yml | findings | The findings every job kept | plumbing | |
| conformance.auto.yml | findings | The findings, merged; the pipeline is sound where every cell that ran left its file (ci/collect.ts) | red-cause | reports-not-produced |
| conformance.auto.yml | findings | The merged findings, kept for the site | plumbing | |
| conformance.auto.yml | keep-findings | actions/checkout@v4 | plumbing | |
| conformance.auto.yml | keep-findings | ./.github/actions/bun | plumbing | |
| conformance.auto.yml | keep-findings | The merged findings of this workflow | plumbing | |
| conformance.auto.yml | keep-findings | The findings added to the history branch (the only writer) | plumbing | |
| evidence.auto.yml | plan | actions/checkout@v4 | red-cause | plan-unavailable |
| evidence.auto.yml | plan | ./.github/actions/bun | red-cause | plan-unavailable |
| evidence.auto.yml | plan | The packages the plan reads, from the root's bun.lock | red-cause | plan-unavailable |
| evidence.auto.yml | plan | The libraries, linked by name before any of them is imported (the root's packages are old copies from npm) | red-cause | plan-unavailable |
| evidence.auto.yml | plan | Every library, as a matrix | red-cause | plan-unavailable |
| evidence.auto.yml | tests | actions/checkout@v4 | plumbing | |
| evidence.auto.yml | tests | ./.github/actions/bun | plumbing | |
| evidence.auto.yml | tests | The development tools, from bun.lock (the libraries it imports are linked) | finding | install, 7 min |
| evidence.auto.yml | tests | The test runner's own packages (commons quality) | finding | install, 7 min |
| evidence.auto.yml | tests | The packages of the tool that keeps the report (commons docs) | finding | install, 7 min |
| evidence.auto.yml | tests | The tests, kept as a CTRF report | finding | bun-test, 20 min |
| evidence.auto.yml | tests | Why there is a report, or none | finding | exit-status, 20 min |
| evidence.auto.yml | tests | The report and its status, kept for the site | plumbing | |
| evidence.auto.yml | tests | The findings of this job, kept for the job that gathers them | plumbing | |
| evidence.auto.yml | repository | actions/checkout@v4 | plumbing | |
| evidence.auto.yml | repository | ./.github/actions/bun | plumbing | |
| evidence.auto.yml | repository | The root's development tools, from bun.lock | finding | install, 7 min |
| evidence.auto.yml | repository | The documentation generator's dependencies, which the tests of the root import | finding | install, 7 min |
| evidence.auto.yml | repository | The test runner's own packages (commons quality) | finding | install, 7 min |
| evidence.auto.yml | repository | The libraries, linked by name | finding | exit-status, 20 min |
| evidence.auto.yml | repository | The tests, kept as a CTRF report | finding | bun-test, 20 min |
| evidence.auto.yml | repository | Why there is a report, or none | finding | exit-status, 20 min |
| evidence.auto.yml | repository | The report and its status, kept for the site | plumbing | |
| evidence.auto.yml | repository | The findings of this job, kept for the job that gathers them | plumbing | |
| evidence.auto.yml | mutation | actions/checkout@v4 | plumbing | |
| evidence.auto.yml | mutation | ./.github/actions/bun | plumbing | |
| evidence.auto.yml | mutation | The development tools, from bun.lock (the libraries it imports are linked) | finding | install, 12 min |
| evidence.auto.yml | mutation | The packages of the tool that keeps the report (commons docs) | finding | install, 12 min |
| evidence.auto.yml | mutation | The mutation run, kept as a small report | finding | exit-status, 36 min |
| evidence.auto.yml | mutation | The score, kept for the site | plumbing | |
| evidence.auto.yml | mutation | The findings of this job, kept for the job that gathers them | plumbing | |
| evidence.auto.yml | collect | actions/checkout@v4 | plumbing | |
| evidence.auto.yml | collect | ./.github/actions/bun | plumbing | |
| evidence.auto.yml | collect | The packages of the tool that keeps the history (commons docs) | finding | install, 3 min |
| evidence.auto.yml | collect | The reports of the tests | plumbing | |
| evidence.auto.yml | collect | Which run this is | finding | exit-status, 8 min |
| evidence.auto.yml | collect | The run, added to the history | finding | exit-status, 5 min |
| evidence.auto.yml | collect | The evidence, kept for the site | plumbing | |
| evidence.auto.yml | collect | The findings of this job, kept for the job that gathers them | plumbing | |
| evidence.auto.yml | findings | actions/checkout@v4 | red-cause | reports-not-produced |
| evidence.auto.yml | findings | ./.github/actions/bun | red-cause | reports-not-produced |
| evidence.auto.yml | findings | The findings every job kept | plumbing | |
| evidence.auto.yml | findings | The findings, merged; the pipeline is sound where every cell that ran left its file (ci/collect.ts) | red-cause | reports-not-produced |
| evidence.auto.yml | findings | The merged findings, kept for the site | plumbing | |
| evidence.auto.yml | keep-findings | actions/checkout@v4 | plumbing | |
| evidence.auto.yml | keep-findings | ./.github/actions/bun | plumbing | |
| evidence.auto.yml | keep-findings | The merged findings of this workflow | plumbing | |
| evidence.auto.yml | keep-findings | The findings added to the history branch (the only writer) | plumbing | |
| release.auto.yml | plan | actions/checkout@v4 | red-cause | plan-unavailable |
| release.auto.yml | plan | ./.github/actions/bun | red-cause | plan-unavailable |
| release.auto.yml | plan | The packages the plan reads, from the root's bun.lock | red-cause | plan-unavailable |
| release.auto.yml | plan | The libraries, linked by name before any of them is imported (the root's packages are old copies from npm) | red-cause | plan-unavailable |
| release.auto.yml | plan | The libraries to release, in dependency order, from the record | red-cause | plan-unavailable |
| release.auto.yml | build | actions/checkout@v4 | plumbing | |
| release.auto.yml | build | ./.github/actions/bun | plumbing | |
| release.auto.yml | build | The development tools, from bun.lock | finding | install, 6 min |
| release.auto.yml | build | verify, which includes the packing | finding | verify, 16 min |
| release.auto.yml | build | The package that is published | finding | exit-status, 16 min |
| release.auto.yml | build | The tarball, kept for the job that publishes it | plumbing | |
| release.auto.yml | build | The findings of this job, kept for the job that gathers them | plumbing | |
| release.auto.yml | publish | actions/checkout@v4 | plumbing | |
| release.auto.yml | publish | ./.github/actions/bun | plumbing | |
| release.auto.yml | publish | The packages the command reads, from the root's bun.lock | finding | install, 18 min |
| release.auto.yml | publish | The libraries, linked by name before any of them is imported | finding | exit-status, 48 min |
| release.auto.yml | publish | actions/setup-node@v4 | plumbing | |
| release.auto.yml | publish | The tarballs | plumbing | |
| release.auto.yml | publish | The release policy of the day, and the findings that are open (commons 0038-build-policy FR-010) | gate | release |
| release.auto.yml | publish | Published in dependency order to npm and to the GitHub package registry, and tagged: each release by itself, a version already on npm is only tagged | gate | release |
| release.auto.yml | publish | The findings of this job, kept for the job that gathers them | plumbing | |
| release.auto.yml | findings | actions/checkout@v4 | red-cause | reports-not-produced |
| release.auto.yml | findings | ./.github/actions/bun | red-cause | reports-not-produced |
| release.auto.yml | findings | The findings every job kept | plumbing | |
| release.auto.yml | findings | The findings, merged; the pipeline is sound where every cell that ran left its file (ci/collect.ts) | red-cause | reports-not-produced |
| release.auto.yml | findings | The merged findings, kept for the site | plumbing | |
| release.auto.yml | keep-findings | actions/checkout@v4 | plumbing | |
| release.auto.yml | keep-findings | ./.github/actions/bun | plumbing | |
| release.auto.yml | keep-findings | The merged findings of this workflow | plumbing | |
| release.auto.yml | keep-findings | The findings added to the history branch (the only writer) | plumbing | |
| site.auto.yml | check | actions/checkout@v4 | plumbing | |
| site.auto.yml | check | ./.github/actions/bun | plumbing | |
| site.auto.yml | check | TypeScript 7.1 (beta), Shiki, beautiful-mermaid and @types/node, exactly as bun.lock pins them | finding | install, 4 min |
| site.auto.yml | check | The compiler, the generator's tests, then check on commons | finding | verify, 12 min |
| site.auto.yml | check | The findings of this job, kept for the job that gathers them | plumbing | |
| site.auto.yml | site | actions/checkout@v4 | plumbing | |
| site.auto.yml | site | ./.github/actions/bun | plumbing | |
| site.auto.yml | site | TypeScript 7.1 (beta), Shiki, beautiful-mermaid and @types/node, exactly as bun.lock pins them | finding | install, 6 min |
| site.auto.yml | site | The newest test reports | finding | exit-status, 10 min |
| site.auto.yml | site | The findings of the runs, from the history branch, and the accepted risks | finding | exit-status, 10 min |
| site.auto.yml | site | The open issues, the runs of the workflows, and which build this is | finding | exit-status, 10 min |
| site.auto.yml | site | The site, built | finding | exit-status, 16 min |
| site.auto.yml | site | The emergency page, where the build failed | finding | exit-status, 16 min |
| site.auto.yml | site | The site, kept for Pages | gate | pages |
| site.auto.yml | site | The findings of this job, kept for the job that gathers them | plumbing | |
| site.auto.yml | publish | Published to GitHub Pages | gate | pages |
| site.auto.yml | findings | actions/checkout@v4 | red-cause | reports-not-produced |
| site.auto.yml | findings | ./.github/actions/bun | red-cause | reports-not-produced |
| site.auto.yml | findings | The findings every job kept | plumbing | |
| site.auto.yml | findings | The findings, merged; the pipeline is sound where every cell that ran left its file (ci/collect.ts) | red-cause | reports-not-produced |
| site.auto.yml | findings | The merged findings, kept for the site | plumbing | |
| site.auto.yml | keep-findings | actions/checkout@v4 | plumbing | |
| site.auto.yml | keep-findings | ./.github/actions/bun | plumbing | |
| site.auto.yml | keep-findings | The merged findings of this workflow | plumbing | |
| site.auto.yml | keep-findings | The findings added to the history branch (the only writer) | plumbing | |
| tests.auto.yml | check | actions/checkout@v4 | plumbing | |
| tests.auto.yml | check | ./.github/actions/bun | plumbing | |
| tests.auto.yml | check | The root's development tools, from bun.lock | finding | install, 4 min |
| tests.auto.yml | check | The documentation generator's dependencies, which the tests of the root import | finding | install, 4 min |
| tests.auto.yml | check | TypeScript 7 on the tests of the root and on commons' tools | finding | tsc, 9 min |
| tests.auto.yml | check | The formatter | finding | format, 9 min |
| tests.auto.yml | check | The linter, type-aware, no warning allowed | finding | lint, 9 min |
| tests.auto.yml | check | Commons' generated files and specifications, as a person checks them, on Bun and on Node 26 | finding | checks, 12 min |
| tests.auto.yml | check | The findings of this job, kept for the job that gathers them | plumbing | |
| tests.auto.yml | tests | actions/checkout@v4 | plumbing | |
| tests.auto.yml | tests | ./.github/actions/bun | plumbing | |
| tests.auto.yml | tests | The root's development tools, from bun.lock | finding | install, 4 min |
| tests.auto.yml | tests | ShellCheck, which the packaging test uses where it is installed | finding | exit-status, 12 min |
| tests.auto.yml | tests | Independent validators of the exports (rdflib, pySHACL, jsonschema), which the Mizan test uses where they are installed | finding | exit-status, 12 min |
| tests.auto.yml | tests | The tests on Bun (tests/release/ is the release's: it packs, installs and type-checks every library) | finding | bun-test, 12 min |
| tests.auto.yml | tests | The tests on Node 26 | finding | bun-test, 12 min |
| tests.auto.yml | tests | The findings of this job, kept for the job that gathers them | plumbing | |
| tests.auto.yml | workflows | actions/checkout@v4 | plumbing | |
| tests.auto.yml | workflows | ./.github/actions/bun | plumbing | |
| tests.auto.yml | workflows | The workflow files are what the model makes, on Bun and on Node 26 | red-cause | workflow-invalid |
| tests.auto.yml | windows | actions/checkout@v4 | plumbing | |
| tests.auto.yml | windows | ./.github/actions/bun | plumbing | |
| tests.auto.yml | windows | Commons' generated files and specifications, on Bun and on Node 26 | finding | checks, 12 min |
| tests.auto.yml | windows | The findings of this job, kept for the job that gathers them | plumbing | |
| tests.auto.yml | robot | actions/checkout@v4 | plumbing | |
| tests.auto.yml | robot | ROBOT, pinned | finding | exit-status, 8 min |
| tests.auto.yml | robot | Convert, reason and report, for each ontology | finding | exit-status, 8 min |
| tests.auto.yml | robot | The findings of this job, kept for the job that gathers them | plumbing | |
| tests.auto.yml | findings | actions/checkout@v4 | red-cause | reports-not-produced |
| tests.auto.yml | findings | ./.github/actions/bun | red-cause | reports-not-produced |
| tests.auto.yml | findings | The findings every job kept | plumbing | |
| tests.auto.yml | findings | The findings, merged; the pipeline is sound where every cell that ran left its file (ci/collect.ts) | red-cause | reports-not-produced |
| tests.auto.yml | findings | The merged findings, kept for the site | plumbing | |
| tests.auto.yml | keep-findings | actions/checkout@v4 | plumbing | |
| tests.auto.yml | keep-findings | ./.github/actions/bun | plumbing | |
| tests.auto.yml | keep-findings | The merged findings of this workflow | plumbing | |
| tests.auto.yml | keep-findings | The findings added to the history branch (the only writer) | plumbing |