IF Commons GitHub

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

  • ci plans from what a push or pull request changed (commons/libraries/src/plan.ts, the same affected-libraries code as dev:check), then runs verify and the tests on Node 26 for the libraries that change affects, on Linux; and on Windows and macOS only for the libraries whose record in LIBRARY_CI names them. Its job ci is the one result to require.
  • tests runs 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 check covers the same ground by hand).
  • conformance runs 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 and ifc-docs check gate 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

  • evidence runs by the hour and by hand, never on a push: the tests of every library and of the repository's own tests/ (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_LIBRARIES in the definitions), and a collect job 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.
  • site builds on every push to main from 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

  • release is run by hand from main after repoctl release apply has 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.

WorkflowFileStarts onJobsWhat it is for
ci.github/workflows/ci.auto.ymlpush (paths of commons), pull request, by hand, schedule 17 3 * * * (UTC)plan, verify, systems, ci, keep-findingsThe 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.ymlpush (paths of commons), pull requestotel-conformance, compile, findings, keep-findingsWhat 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.ymlby hand, schedule 17 * * * * (UTC), schedule 43 3 * * * (UTC)plan, tests, repository, mutation, collect, findings, keep-findingsThe 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.ymlby handplan, build, publish, findings, keep-findingsThe 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.ymlpush (paths of commons), pull request, by hand, schedule 41 4 * * * (UTC), after evidence, ci, release, tests, conformancecheck, site, publish, findings, keep-findingsThe 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.ymlpush to main, pull requestcheck, tests, workflows, windows, robot, findings, keep-findingsThe 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 causeWhy it is one
workflow-invalida 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-misusedthe 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-unavailablewhen 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-producedwhen 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.

WorkflowJobStepIsDetail
ci.auto.ymlplanactions/checkout@v4red-causeplan-unavailable
ci.auto.ymlplan./.github/actions/bunred-causeplan-unavailable
ci.auto.ymlplanThe packages the plan reads, from the root's bun.lockred-causeplan-unavailable
ci.auto.ymlplanThe libraries, linked by name before any of them is imported (the root's packages are old copies from npm)red-causeplan-unavailable
ci.auto.ymlplanThe libraries this change affects, and the systems each runs onred-causeplan-unavailable
ci.auto.ymlverifyactions/checkout@v4plumbing
ci.auto.ymlverify./.github/actions/bunplumbing
ci.auto.ymlverifyThe development tools, from bun.lock (the libraries it imports are linked)findinginstall, 6 min
ci.auto.ymlverifyverify (its packing is checked where the exports changed, and by the release)findingverify, 16 min
ci.auto.ymlverifyAfter verifyfindingverify, 16 min
ci.auto.ymlverifyThe tests on Node 26findingbun-test, 16 min
ci.auto.ymlverifyThe findings of this job, kept for the job that gathers themplumbing
ci.auto.ymlsystemsactions/checkout@v4plumbing
ci.auto.ymlsystems./.github/actions/bunplumbing
ci.auto.ymlsystemsThe development tools, from bun.lock (the libraries it imports are linked)findinginstall, 6 min
ci.auto.ymlsystemsverify (its packing is checked where the exports changed, and by the release)findingverify, 16 min
ci.auto.ymlsystemsAfter verifyfindingverify, 16 min
ci.auto.ymlsystemsThe tests on Node 26findingbun-test, 16 min
ci.auto.ymlsystemsThe findings of this job, kept for the job that gathers themplumbing
ci.auto.ymlciactions/checkout@v4red-causereports-not-produced
ci.auto.ymlci./.github/actions/bunred-causereports-not-produced
ci.auto.ymlciThe findings every job keptplumbing
ci.auto.ymlciThe findings, merged; the pipeline is sound where every cell that ran left its file (ci/collect.ts)red-causereports-not-produced
ci.auto.ymlciThe merged findings, kept for the siteplumbing
ci.auto.ymlkeep-findingsactions/checkout@v4plumbing
ci.auto.ymlkeep-findings./.github/actions/bunplumbing
ci.auto.ymlkeep-findingsThe merged findings of this workflowplumbing
ci.auto.ymlkeep-findingsThe findings added to the history branch (the only writer)plumbing
conformance.auto.ymlotel-conformanceactions/checkout@v4plumbing
conformance.auto.ymlotel-conformance./.github/actions/bunplumbing
conformance.auto.ymlotel-conformanceThe development tools, from bun.lockfindinginstall, 3 min
conformance.auto.ymlotel-conformanceThe OpenTelemetry Collector, verified against commons' pinsfindingexit-status, 8 min
conformance.auto.ymlotel-conformanceThe conformance test, on Bun and on Nodefindingbun-test, 8 min
conformance.auto.ymlotel-conformanceThe findings of this job, kept for the job that gathers themplumbing
conformance.auto.ymlcompileactions/checkout@v4plumbing
conformance.auto.ymlcompile./.github/actions/bunplumbing
conformance.auto.ymlcompileThe development tools, from bun.lockfindinginstall, 3 min
conformance.auto.ymlcompileBuilt for this computer, with an embedded file, and runfindingbun-test, 8 min
conformance.auto.ymlcompileBuilt for Windows from Linux, by the pinned Bun alonefindingexit-status, 8 min
conformance.auto.ymlcompileThe findings of this job, kept for the job that gathers themplumbing
conformance.auto.ymlfindingsactions/checkout@v4red-causereports-not-produced
conformance.auto.ymlfindings./.github/actions/bunred-causereports-not-produced
conformance.auto.ymlfindingsThe findings every job keptplumbing
conformance.auto.ymlfindingsThe findings, merged; the pipeline is sound where every cell that ran left its file (ci/collect.ts)red-causereports-not-produced
conformance.auto.ymlfindingsThe merged findings, kept for the siteplumbing
conformance.auto.ymlkeep-findingsactions/checkout@v4plumbing
conformance.auto.ymlkeep-findings./.github/actions/bunplumbing
conformance.auto.ymlkeep-findingsThe merged findings of this workflowplumbing
conformance.auto.ymlkeep-findingsThe findings added to the history branch (the only writer)plumbing
evidence.auto.ymlplanactions/checkout@v4red-causeplan-unavailable
evidence.auto.ymlplan./.github/actions/bunred-causeplan-unavailable
evidence.auto.ymlplanThe packages the plan reads, from the root's bun.lockred-causeplan-unavailable
evidence.auto.ymlplanThe libraries, linked by name before any of them is imported (the root's packages are old copies from npm)red-causeplan-unavailable
evidence.auto.ymlplanEvery library, as a matrixred-causeplan-unavailable
evidence.auto.ymltestsactions/checkout@v4plumbing
evidence.auto.ymltests./.github/actions/bunplumbing
evidence.auto.ymltestsThe development tools, from bun.lock (the libraries it imports are linked)findinginstall, 7 min
evidence.auto.ymltestsThe test runner's own packages (commons quality)findinginstall, 7 min
evidence.auto.ymltestsThe packages of the tool that keeps the report (commons docs)findinginstall, 7 min
evidence.auto.ymltestsThe tests, kept as a CTRF reportfindingbun-test, 20 min
evidence.auto.ymltestsWhy there is a report, or nonefindingexit-status, 20 min
evidence.auto.ymltestsThe report and its status, kept for the siteplumbing
evidence.auto.ymltestsThe findings of this job, kept for the job that gathers themplumbing
evidence.auto.ymlrepositoryactions/checkout@v4plumbing
evidence.auto.ymlrepository./.github/actions/bunplumbing
evidence.auto.ymlrepositoryThe root's development tools, from bun.lockfindinginstall, 7 min
evidence.auto.ymlrepositoryThe documentation generator's dependencies, which the tests of the root importfindinginstall, 7 min
evidence.auto.ymlrepositoryThe test runner's own packages (commons quality)findinginstall, 7 min
evidence.auto.ymlrepositoryThe libraries, linked by namefindingexit-status, 20 min
evidence.auto.ymlrepositoryThe tests, kept as a CTRF reportfindingbun-test, 20 min
evidence.auto.ymlrepositoryWhy there is a report, or nonefindingexit-status, 20 min
evidence.auto.ymlrepositoryThe report and its status, kept for the siteplumbing
evidence.auto.ymlrepositoryThe findings of this job, kept for the job that gathers themplumbing
evidence.auto.ymlmutationactions/checkout@v4plumbing
evidence.auto.ymlmutation./.github/actions/bunplumbing
evidence.auto.ymlmutationThe development tools, from bun.lock (the libraries it imports are linked)findinginstall, 12 min
evidence.auto.ymlmutationThe packages of the tool that keeps the report (commons docs)findinginstall, 12 min
evidence.auto.ymlmutationThe mutation run, kept as a small reportfindingexit-status, 36 min
evidence.auto.ymlmutationThe score, kept for the siteplumbing
evidence.auto.ymlmutationThe findings of this job, kept for the job that gathers themplumbing
evidence.auto.ymlcollectactions/checkout@v4plumbing
evidence.auto.ymlcollect./.github/actions/bunplumbing
evidence.auto.ymlcollectThe packages of the tool that keeps the history (commons docs)findinginstall, 3 min
evidence.auto.ymlcollectThe reports of the testsplumbing
evidence.auto.ymlcollectWhich run this isfindingexit-status, 8 min
evidence.auto.ymlcollectThe run, added to the historyfindingexit-status, 5 min
evidence.auto.ymlcollectThe evidence, kept for the siteplumbing
evidence.auto.ymlcollectThe findings of this job, kept for the job that gathers themplumbing
evidence.auto.ymlfindingsactions/checkout@v4red-causereports-not-produced
evidence.auto.ymlfindings./.github/actions/bunred-causereports-not-produced
evidence.auto.ymlfindingsThe findings every job keptplumbing
evidence.auto.ymlfindingsThe findings, merged; the pipeline is sound where every cell that ran left its file (ci/collect.ts)red-causereports-not-produced
evidence.auto.ymlfindingsThe merged findings, kept for the siteplumbing
evidence.auto.ymlkeep-findingsactions/checkout@v4plumbing
evidence.auto.ymlkeep-findings./.github/actions/bunplumbing
evidence.auto.ymlkeep-findingsThe merged findings of this workflowplumbing
evidence.auto.ymlkeep-findingsThe findings added to the history branch (the only writer)plumbing
release.auto.ymlplanactions/checkout@v4red-causeplan-unavailable
release.auto.ymlplan./.github/actions/bunred-causeplan-unavailable
release.auto.ymlplanThe packages the plan reads, from the root's bun.lockred-causeplan-unavailable
release.auto.ymlplanThe libraries, linked by name before any of them is imported (the root's packages are old copies from npm)red-causeplan-unavailable
release.auto.ymlplanThe libraries to release, in dependency order, from the recordred-causeplan-unavailable
release.auto.ymlbuildactions/checkout@v4plumbing
release.auto.ymlbuild./.github/actions/bunplumbing
release.auto.ymlbuildThe development tools, from bun.lockfindinginstall, 6 min
release.auto.ymlbuildverify, which includes the packingfindingverify, 16 min
release.auto.ymlbuildThe package that is publishedfindingexit-status, 16 min
release.auto.ymlbuildThe tarball, kept for the job that publishes itplumbing
release.auto.ymlbuildThe findings of this job, kept for the job that gathers themplumbing
release.auto.ymlpublishactions/checkout@v4plumbing
release.auto.ymlpublish./.github/actions/bunplumbing
release.auto.ymlpublishThe packages the command reads, from the root's bun.lockfindinginstall, 18 min
release.auto.ymlpublishThe libraries, linked by name before any of them is importedfindingexit-status, 48 min
release.auto.ymlpublishactions/setup-node@v4plumbing
release.auto.ymlpublishThe tarballsplumbing
release.auto.ymlpublishThe release policy of the day, and the findings that are open (commons 0038-build-policy FR-010)gaterelease
release.auto.ymlpublishPublished in dependency order to npm and to the GitHub package registry, and tagged: each release by itself, a version already on npm is only taggedgaterelease
release.auto.ymlpublishThe findings of this job, kept for the job that gathers themplumbing
release.auto.ymlfindingsactions/checkout@v4red-causereports-not-produced
release.auto.ymlfindings./.github/actions/bunred-causereports-not-produced
release.auto.ymlfindingsThe findings every job keptplumbing
release.auto.ymlfindingsThe findings, merged; the pipeline is sound where every cell that ran left its file (ci/collect.ts)red-causereports-not-produced
release.auto.ymlfindingsThe merged findings, kept for the siteplumbing
release.auto.ymlkeep-findingsactions/checkout@v4plumbing
release.auto.ymlkeep-findings./.github/actions/bunplumbing
release.auto.ymlkeep-findingsThe merged findings of this workflowplumbing
release.auto.ymlkeep-findingsThe findings added to the history branch (the only writer)plumbing
site.auto.ymlcheckactions/checkout@v4plumbing
site.auto.ymlcheck./.github/actions/bunplumbing
site.auto.ymlcheckTypeScript 7.1 (beta), Shiki, beautiful-mermaid and @types/node, exactly as bun.lock pins themfindinginstall, 4 min
site.auto.ymlcheckThe compiler, the generator's tests, then check on commonsfindingverify, 12 min
site.auto.ymlcheckThe findings of this job, kept for the job that gathers themplumbing
site.auto.ymlsiteactions/checkout@v4plumbing
site.auto.ymlsite./.github/actions/bunplumbing
site.auto.ymlsiteTypeScript 7.1 (beta), Shiki, beautiful-mermaid and @types/node, exactly as bun.lock pins themfindinginstall, 6 min
site.auto.ymlsiteThe newest test reportsfindingexit-status, 10 min
site.auto.ymlsiteThe findings of the runs, from the history branch, and the accepted risksfindingexit-status, 10 min
site.auto.ymlsiteThe open issues, the runs of the workflows, and which build this isfindingexit-status, 10 min
site.auto.ymlsiteThe site, builtfindingexit-status, 16 min
site.auto.ymlsiteThe emergency page, where the build failedfindingexit-status, 16 min
site.auto.ymlsiteThe site, kept for Pagesgatepages
site.auto.ymlsiteThe findings of this job, kept for the job that gathers themplumbing
site.auto.ymlpublishPublished to GitHub Pagesgatepages
site.auto.ymlfindingsactions/checkout@v4red-causereports-not-produced
site.auto.ymlfindings./.github/actions/bunred-causereports-not-produced
site.auto.ymlfindingsThe findings every job keptplumbing
site.auto.ymlfindingsThe findings, merged; the pipeline is sound where every cell that ran left its file (ci/collect.ts)red-causereports-not-produced
site.auto.ymlfindingsThe merged findings, kept for the siteplumbing
site.auto.ymlkeep-findingsactions/checkout@v4plumbing
site.auto.ymlkeep-findings./.github/actions/bunplumbing
site.auto.ymlkeep-findingsThe merged findings of this workflowplumbing
site.auto.ymlkeep-findingsThe findings added to the history branch (the only writer)plumbing
tests.auto.ymlcheckactions/checkout@v4plumbing
tests.auto.ymlcheck./.github/actions/bunplumbing
tests.auto.ymlcheckThe root's development tools, from bun.lockfindinginstall, 4 min
tests.auto.ymlcheckThe documentation generator's dependencies, which the tests of the root importfindinginstall, 4 min
tests.auto.ymlcheckTypeScript 7 on the tests of the root and on commons' toolsfindingtsc, 9 min
tests.auto.ymlcheckThe formatterfindingformat, 9 min
tests.auto.ymlcheckThe linter, type-aware, no warning allowedfindinglint, 9 min
tests.auto.ymlcheckCommons' generated files and specifications, as a person checks them, on Bun and on Node 26findingchecks, 12 min
tests.auto.ymlcheckThe findings of this job, kept for the job that gathers themplumbing
tests.auto.ymltestsactions/checkout@v4plumbing
tests.auto.ymltests./.github/actions/bunplumbing
tests.auto.ymltestsThe root's development tools, from bun.lockfindinginstall, 4 min
tests.auto.ymltestsShellCheck, which the packaging test uses where it is installedfindingexit-status, 12 min
tests.auto.ymltestsIndependent validators of the exports (rdflib, pySHACL, jsonschema), which the Mizan test uses where they are installedfindingexit-status, 12 min
tests.auto.ymltestsThe tests on Bun (tests/release/ is the release's: it packs, installs and type-checks every library)findingbun-test, 12 min
tests.auto.ymltestsThe tests on Node 26findingbun-test, 12 min
tests.auto.ymltestsThe findings of this job, kept for the job that gathers themplumbing
tests.auto.ymlworkflowsactions/checkout@v4plumbing
tests.auto.ymlworkflows./.github/actions/bunplumbing
tests.auto.ymlworkflowsThe workflow files are what the model makes, on Bun and on Node 26red-causeworkflow-invalid
tests.auto.ymlwindowsactions/checkout@v4plumbing
tests.auto.ymlwindows./.github/actions/bunplumbing
tests.auto.ymlwindowsCommons' generated files and specifications, on Bun and on Node 26findingchecks, 12 min
tests.auto.ymlwindowsThe findings of this job, kept for the job that gathers themplumbing
tests.auto.ymlrobotactions/checkout@v4plumbing
tests.auto.ymlrobotROBOT, pinnedfindingexit-status, 8 min
tests.auto.ymlrobotConvert, reason and report, for each ontologyfindingexit-status, 8 min
tests.auto.ymlrobotThe findings of this job, kept for the job that gathers themplumbing
tests.auto.ymlfindingsactions/checkout@v4red-causereports-not-produced
tests.auto.ymlfindings./.github/actions/bunred-causereports-not-produced
tests.auto.ymlfindingsThe findings every job keptplumbing
tests.auto.ymlfindingsThe findings, merged; the pipeline is sound where every cell that ran left its file (ci/collect.ts)red-causereports-not-produced
tests.auto.ymlfindingsThe merged findings, kept for the siteplumbing
tests.auto.ymlkeep-findingsactions/checkout@v4plumbing
tests.auto.ymlkeep-findings./.github/actions/bunplumbing
tests.auto.ymlkeep-findingsThe merged findings of this workflowplumbing
tests.auto.ymlkeep-findingsThe findings added to the history branch (the only writer)plumbing

Titles, headings, exports, tables, columns and requirements. Esc closes.