Skip to content

CI and supply chain

What workflows may run and how they are written.

Rule Level Applies to Verified
KB-CI-001 Only allow-listed actions, pinned to a full commit SHA must all checked
KB-CI-002 Least privilege in every workflow must all planned
KB-CI-003 Workflows call the shared ci-tools workflows at @v1 must all planned
KB-CI-004 The CI gate needs every other job, including DCO must all checked
KB-CI-005 Code from a fork never runs with secrets must all planned
KB-CI-006 Dependabot keeps the actions current should all planned
KB-CI-007 Public repositories run GitHub's security features must all planned
KB-CI-008 No credentials, private datasheets or personal data are committed must all planned
KB-CI-009 Tags that start workflows are pushed with a GitHub App token should all review
KB-CI-010 Every example builds in CI, and a platform arrives with its job must driver, library, hal, firmware, template planned
KB-CI-011 kb-core CI builds every part for every MCU family and for no MCU must library planned
KB-CI-012 Tables generated from compat.yml are never stale must library planned
KB-CI-013 Every board HAL runs the kb-hal-common lints must hal planned
KB-CI-014 version_lock.txt matches the submodule pins must hal, firmware planned
KB-CI-015 ESP-IDF builds run the declared IDF matrix, validated first guide driver, library, hal, firmware, template review
KB-CI-016 CI keeps the test and coverage reports as artifacts should driver, library, hal, firmware (high level and above) planned

KB-CI-001: Only allow-listed actions, pinned to a full commit SHA

MUST · all · since 1.0

Workflows use GitHub's own actions, the organisation's, or a third-party action on the allow-list in .github/org/actions-allowlist.json, always pinned to a full commit SHA with the version in a comment.

Verified by:

  • actions-allowlist (implemented): only allow-listed actions, pinned to a full commit SHA, can run (organisation Actions policy)

KB-CI-002: Least privilege in every workflow

Proposed

Enforced in ci-tools' own workflows today; the reusable check is planned.

MUST · all · since 1.0 · enforced from 2027-01-15

Each workflow sets permissions: at the top (read or none) and each job asks only for what it needs; a workflow never interpolates untrusted input into a shell command.

Verified by:

  • workflow-permissions (planned): every workflow sets permissions at the top and grants each job the least it needs
  • actionlint (planned): actionlint and zizmor find nothing in the repository's workflows

KB-CI-003: Workflows call the shared ci-tools workflows at @v1

Proposed

Warns until 2027-03-01, then fails CI. driver-template's host tests still use their own workflow rather than ru-host-ci. The v1 side is enforced today by ci-tools' release.yml and the major-tags ruleset.

MUST · all · since 1.0 · enforced from 2027-03-01

Lint, analysis, build, docs and release jobs call kokeb-labs/ci-tools/.github/workflows/<name>.yml@v1, never @main or a copy. ci-tools stays at 1.x and moves v1 only to its highest 1.x release.

Verified by:

  • shared-workflows (planned): every lint, analysis, build, docs and release job calls a kokeb-labs/ci-tools reusable workflow at @v1, and none at @main
  • review: A job that does not use a ci-tools workflow says why in a comment beside it.

Explained in: standards/repo-governance.md

KB-CI-004: The CI gate needs every other job, including DCO

MUST · all · since 1.0

The workflow's last job comes from ru-ci-gate, runs with if: always() and lists every other job in needs, so a skipped or failed job, an unsigned commit or a [skip ci] run cannot merge.

Verified by:

  • ci-gate (implemented): one required check that passes only when every job of the workflow passed
  • dco (implemented): every commit of a pull request has a Signed-off-by line matching its author

See also: IEC 62304:2006+A1:2015 8.2 (a change is verified before it is accepted)

Explained in: standards/repo-governance.md

KB-CI-005: Code from a fork never runs with secrets

MUST · all · since 1.0

Workflows triggered by a fork's pull request get no secrets and a read-only token; pull_request_target and workflow_run never check out or run the pull request's code. Fork runs wait for a maintainer's approval.

Verified by:

  • actionlint (planned): actionlint and zizmor find nothing in the repository's workflows
  • review: No workflow triggered by pull_request_target or workflow_run checks out the pull request head.

Explained in: standards/repo-governance.md

KB-CI-006: Dependabot keeps the actions current

Proposed

Warns until 2027-03-01, then fails CI. driver-template has the file; org-standard-check does not ask for it.

SHOULD · all · since 1.0 · enforced from 2027-03-01

Every repository with workflows has .github/dependabot.yml updating github-actions weekly with the dependencies label and the ci prefix, plus pip where it has Python tooling. It never manages submodules.

Verified by:

  • dependabot-config (planned): .github/dependabot.yml updates github-actions weekly with label dependencies and prefix ci, pip where Python tooling exists, and has no gitsubmodule ecosystem

Explained in: standards/repo-governance.md

KB-CI-007: Public repositories run GitHub's security features

MUST · all · since 1.0

Secret scanning with push protection, Dependabot alerts and security updates, private vulnerability reporting and CodeQL default setup are on for every public repository.

Verified by:

  • org-settings-drift (planned): a scheduled kokeb_org.py --check finds no drift between org/ and the repository's live settings
  • review: kokeb_org.py --check --section security reports no drift for the repository.

Explained in: standards/repo-governance.md

KB-CI-008: No credentials, private datasheets or personal data are committed

MUST · all · since 1.0

Tokens, keys, passwords, private datasheet material and personal data never enter a commit, a log or an artifact. A secret that reached a commit is revoked, not just removed.

Verified by:

  • secret-scan (planned): gitleaks finds no secret in the pull request's commits
  • review: Nothing in the diff, the logs or the artifacts is a credential or confidential material.

Explained in: standards/agents.md

KB-CI-009: Tags that start workflows are pushed with a GitHub App token

SHOULD · all · since 1.0

A workflow that pushes a tag other workflows react to uses a token from actions/create-github-app-token, because tags pushed with GITHUB_TOKEN start no workflow.

Verified by:

  • review: A tag push meant to trigger release or docs workflows uses a GitHub App token.

Explained in: standards/release.md

KB-CI-010: Every example builds in CI, and a platform arrives with its job

Proposed

Warns until 2027-03-01, then fails CI. driver-template builds its ESP32 example through ru-build today; nothing maps example folders to jobs.

MUST · driver, library, hal, firmware, template · since 1.0 · enforced from 2027-03-01

Each examples/<platform>/ has a CI job that builds it (ru-build for ESP-IDF). A platform is added only in the pull request that adds that job.

Verified by:

  • examples-build (planned): every examples/<platform>/ folder is built by a job of the repository's CI

Explained in: standards/driver.md

KB-CI-011: kb-core CI builds every part for every MCU family and for no MCU

Proposed

Warns until 2027-03-01, then fails CI. The standard describes this matrix as enforced; ci-tools has none.

MUST · library · since 1.0 · enforced from 2027-03-01

kb-core CI builds each target with KB_MCU=NONE, KB_MCU=HOST and each family, STM32 with stub SDK headers, so every handler compiles everywhere. An all-options ESP32 example proves every toggle builds.

Verified by:

  • mcu-matrix (planned): kb-core CI builds every target for each MCU family (STM32 with stub headers), KB_MCU=HOST and NONE

See also: ADR-0013; ADR-0014

Explained in: standards/library.md

KB-CI-012: Tables generated from compat.yml are never stale

Proposed

Warns until 2027-03-01, then fails CI.

MUST · library · since 1.0 · enforced from 2027-03-01

The MCU gate table and every other table generated from catalog/compat.yml are regenerated in CI, and any difference fails.

Verified by:

  • compat-table (planned): regenerating the tables derived from catalog/compat.yml leaves the tree unchanged

See also: ADR-0014

Explained in: standards/library.md

KB-CI-013: Every board HAL runs the kb-hal-common lints

Proposed

Warns until 2027-03-01, then fails CI. The lints live only in kb-hal-common; there is no reusable workflow for board HALs yet.

MUST · hal · since 1.0 · enforced from 2027-03-01

Board HAL CI runs the boundary, driver-access, allocation and lock lints that kb-hal-common ships. An exception sits in the lint's allow-list with the issue that will remove it.

Verified by:

  • hal-lints (planned): the kb-hal-common boundary, driver-access, allocation and lock lints pass in the board HAL

See also: ADR-0005

Explained in: standards/hal.md

KB-CI-014: version_lock.txt matches the submodule pins

Proposed

Warns until 2027-03-01, then fails CI.

MUST · hal, firmware · since 1.0 · enforced from 2027-03-01

A board HAL or product lists each submodule in version_lock.txt as REF_<repo>=vX.Y.Z@<sha>, and CI fails when a line does not match the pinned commit and its tag.

Verified by:

  • version-lock (planned): each version_lock.txt line REF_<repo>=vX.Y.Z@<sha> matches the submodule's pinned commit and its tag

See also: ADR-0007; IEC 62304:2006+A1:2015 8.1 (identification of configuration items)

Explained in: standards/release.md

KB-CI-015: ESP-IDF builds run the declared IDF matrix, validated first

GUIDE · driver, library, hal, firmware, template · since 1.0

The ESP-IDF versions and targets come from the repository's matrix config, which generate_matrix.py --validate checks before any build. Toolchain and build caches are keyed per IDF version.

Verified by:

  • review: A change to supported IDF versions changes the matrix config, and its validate job passed.

Explained in: standards/driver.md

KB-CI-016: CI keeps the test and coverage reports as artifacts

Proposed

Warns until 2027-03-01, then fails CI. Codecov is not on the actions allow-list, so reports stay as workflow artifacts.

SHOULD · driver, library, hal, firmware (high level and above) · since 1.0 · enforced from 2027-03-01

Host test jobs upload a JUnit test report and the line and branch coverage report, so a release's evidence and any trend can be built from them.

Verified by:

  • test-report (planned): host test jobs upload a JUnit report and a line and branch coverage report as artifacts

Explained in: evidence.md