Skip to content

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.

Quickstart Workflow catalogue Source on GitHub

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-gate turns every job of a workflow into CI gate / gate.
  • C++ checks that agree with the compiler. ru-host-ci builds, runs ctest, then clang-tidy 18 and cppcheck over the same compile database.
  • The documentation platform. ru-mkdocs-publish builds a site with the shared theme in packages/kokeb-mkdocs-theme, checks it, audits it and publishes it, versioned or not (platform guide).
  • ESP-IDF firmware. ru-build builds every app of app_config.yml across ESP-IDF versions and build types with a size report; ru-release-firmware ships the tested firmware (ESP-IDF quickstart).
  • Organisation checks. dco fails a pull request with an unsigned commit; org-standard-check checks 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
  • Quickstart

    The smallest CI for a repository: one workflow, the gate, pinned to @v1.

  • Versioning

    Tags, the moving major, what counts as breaking, releases from the changelog.

  • Permissions contract

    What each workflow needs from its caller, and why a missing grant fails before any job runs.

  • Docs platform

    The theme package, the publish workflow, the migration tool and the style guide.

  • Workflow catalogue

    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.