Kokeb Labs CI and documentation platform
CI Tools¶
Reusable GitHub Actions workflows that every Kokeb Labs repository calls: C/C++ lint and analysis, host builds and
tests, ESP-IDF firmware builds, the documentation platform, link and lint checks, the DCO sign-off and
organisation-standard checks, releases, and one required CI gate. Callers pin @v1 and get fixes without
breaking changes.
A repository keeps a few short caller workflows; the jobs, the pinned tools and the checks live here. Every
third-party action is pinned to a commit SHA, so @v1 pins everything a caller runs.
What you get¶
- One required check.
ru-ci-gateturns every job of a workflow intoCI gate / gate. - C++ checks that agree with the compiler.
ru-host-cibuilds, runs ctest, then clang-tidy 18 and cppcheck over the same compile database. - The documentation platform.
ru-mkdocs-publishbuilds a site with the shared theme inpackages/kokeb-mkdocs-theme, checks it, audits it and publishes it, versioned or not (platform guide). - ESP-IDF firmware.
ru-buildbuilds every app ofapp_config.ymlacross ESP-IDF versions and build types with a size report;ru-release-firmwareships the tested firmware (ESP-IDF quickstart). - Organisation checks.
dcofails a pull request with an unsigned commit;org-standard-checkchecks the required root files and the MIT licence. - Releases without breaking callers. Semver tags, a moving
v1, a release for each changelog version a pull request adds, and a check that stops a breaking change from landing without a major (Versioning). - A permissions contract. Each workflow asks for the least it needs, per job, and the self-CI holds it to the documented table.
Workflows¶
| Workflow | Purpose | Permissions |
|---|---|---|
dco.yml |
Fail a pull request when any of its commits lacks a Signed-off-by: line that matches the commit's author. |
contents: read, pull-requests: read |
org-standard-check.yml |
Check that a repository has the root files every Kokeb Labs repository must carry, and that its licence is MIT. | contents: read |
ru-attest-release.yml |
Sign build provenance for every file of a published release. | attestations: write, contents: read, id-token: write |
ru-build.yml |
Build every ESP32 example app of a repository across ESP-IDF versions and build types, upload the firmware and report its size on pull requests. | contents: read, pull-requests: write |
ru-ci-gate.yml |
One required status check per repository: it passes only when every other CI job passed. | contents: read |
ru-cpp-analysis.yml |
Run cppcheck over source folders, without a build, and keep the report as an artifact. | contents: read |
ru-cpp-lint.yml |
Check C and C++ formatting with clang-format and lint with clang-tidy, with results as annotations on the pull request. | contents: read |
ru-cross-build.yml |
Compile a CMake target for microcontroller cores with the GNU Arm Embedded toolchain, so code that claims to run on any MCU is shown to compile for one on every pull request. | contents: read |
ru-docs-linkcheck.yml |
Check every link in a repository's Markdown, external ones included, with lychee. | contents: read |
ru-docs-publish.yml |
Build a Jekyll site with Doxygen and publish it to gh-pages in version folders: the documentation pipeline that ru-mkdocs-publish replaces. |
contents: write |
ru-handbook-check.yml |
Check a repository against the Kokeb Labs handbook rules that a script can decide, and report every finding by rule ID. | contents: read |
ru-host-ci.yml |
Build, test and analyse a CMake project on the host, with clang-tidy 18 and cppcheck over the compiler's own compile database. | contents: read |
ru-host-quality.yml |
Complexity, coverage and sanitizer gates for a CMake C/C++ project, with the limits the Kokeb Labs handbook sets for each assurance level (ADR-0020). | contents: read |
ru-markdown-lint.yml |
Lint Markdown with markdownlint-cli2 against the repository's own rules. | contents: read |
ru-misra.yml |
Check C++ code against MISRA C++:2023 with the validated open-source toolchain, and get a per-guideline report. | contents: read |
ru-mkdocs-publish.yml |
Build, check, audit and publish a Kokeb Labs documentation site with the shared theme, versioned or not. | contents: write |
ru-release-firmware.yml |
Create a GitHub Release for a tag and attach the firmware that ru-build built and tested for the same commit, in public and private repositories. |
actions: read, contents: write |
ru-release-with-artifacts.yml |
Deprecated: use ru-release-firmware, which also works in private repositories. This one creates a GitHub Release for a tag with the firmware that ru-build built for the same commit. |
contents: write |
ru-release.yml |
Create a GitHub Release with generated notes for a tag. | contents: write |
ru-repo-checks.yml |
The small checks of a repository (sign-off, organisation standard, Markdown and YAML lint, handbook rules, template drift and cppcheck) as steps of one job, with the same scripts and failure rules as their single workflows. | contents: read, pull-requests: read |
ru-template-drift.yml |
Find the files a driver or library has let drift from driver-template. | contents: read |
ru-yaml-lint.yml |
Lint YAML files with yamllint against the repository's own rules. | contents: read |
-
The smallest CI for a repository: one workflow, the gate, pinned to
@v1. -
Tags, the moving major, what counts as breaking, releases from the changelog.
-
What each workflow needs from its caller, and why a missing grant fails before any job runs.
-
The theme package, the publish workflow, the migration tool and the style guide.
-
One page per workflow: what it does, jobs, permissions, inputs and failure modes.
-
How this repository tests itself
Self-CI, contract checks and the fixtures every change runs against.