Skip to content

HardFOC CI tools

ESP-IDF CI Tools

Reusable GitHub Actions workflows for ESP-IDF projects. One builds every example app across a matrix of ESP-IDF versions and build types and reports the firmware size; the other attaches that firmware to a GitHub Release.

Quickstart ru-build Source on GitHub

Every HardFOC driver, hf-core, hf-internal-interface-wrap and the board HALs build their ESP32 examples with these workflows. A caller writes about fifteen lines of YAML and pins @v1; the matrix comes from the caller's own app_config.yml, read by the scripts in hf-espidf-project-tools. C++ lint, documentation and the CI gate live in hf-general-ci-tools.

Flow diagram: a calling repository runs ru-build, whose generate-matrix, build and size-report jobs read app_config.yml through hf-espidf-project-tools, build every app in the espressif/idf image and upload fw-* artifacts; on a version tag ru-release-with-artifacts attaches those artifacts to a GitHub Release.Flow diagram: a calling repository runs ru-build, whose generate-matrix, build and size-report jobs read app_config.yml through hf-espidf-project-tools, build every app in the espressif/idf image and upload fw-* artifacts; on a version tag ru-release-with-artifacts attaches those artifacts to a GitHub Release.
From push to release
Figure description and sources

From top to bottom. A HardFOC repository calls ru-build from its ESP32 build workflow. ru-build's first job finds hf-espidf-project-tools (a submodule, the project_tools_dir input, or a clone) and turns app_config.yml into a build matrix. The build job runs once per matrix entry inside the espressif/idf Docker image and uploads the build folder as a fw-* artifact. On pull requests the size-report job comments a size table. When the caller pushes a version tag, ru-release-with-artifacts downloads the fw-* artifacts built for that commit and attaches them to a GitHub Release. Job names are read from the workflow files.

Drawn from: .github/workflows/ru-build.yml jobs; .github/workflows/ru-release-with-artifacts.yml jobs; figure module docs/diagrams/figures/workflow-flow.py.

What it provides

Workflow or action What it does Caller grants
ru-build.yml Builds every app, IDF version and build type in app_config.yml, uploads fw-* artifacts, comments a size table on pull requests contents: read, pull-requests: write
ru-release-with-artifacts.yml On a tag, creates a GitHub Release with the fw-* artifacts built for that commit contents: write
ensure-tools-directory Composite action: finds or clones hf-espidf-project-tools in your own jobs none

What you get

  • One matrix, one source. The apps, ESP-IDF versions, build types and exclusions are read from app_config.yml, the same file the local build scripts use. See ru-build.
  • Builds that survive Docker Hub. The image is pulled up to four times with back-off before the build.
  • A size table on every pull request, and an optional size budget that fails the run.
  • Releases that ship what was tested. The release attaches the artifacts of the build that ran on the tagged commit; nothing is rebuilt. See ru-release-with-artifacts.
  • A stable contract. @v1 never removes an input or asks for a new permission; the self-CI enforces it. See Versioning and the permissions contract.

Where to go next