ru-build¶
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.
File: .github/workflows/ru-build.yml
Caller¶
---
name: ESP32 examples build
on:
push:
branches: [main]
pull_request:
jobs:
build:
uses: kokeb-labs/ci-tools/.github/workflows/ru-build.yml@v1
permissions:
contents: read
pull-requests: write
with:
project_dir: examples/esp32
project_tools_dir: examples/esp32/scripts
max_dec_total: "0"
Inputs¶
| Input | Type | Default | Description |
|---|---|---|---|
project_dir |
string | required | Path to the ESP-IDF project (contains CMakeLists.txt) |
project_tools_dir |
string | empty | Path to project tools directory (contains scripts directly). Leave empty to auto-detect. |
clean_build |
boolean | false |
Skip caches for a clean build. |
auto_clone_tools |
boolean | true |
Auto-clone tools repo if project_tools_dir is missing |
group_build_types |
boolean | true |
Build every build type of an app and IDF version in one job (default), so the runner is prepared and the ESP-IDF image pulled once per app instead of once per build type. false keeps one job per build type. |
idf_install |
string | native |
How the job gets ESP-IDF. native (default): a shallow clone of the IDF version with the tools of the matrix target only, kept in the Actions cache by IDF commit (about 1.1 GB; a warm restore takes seconds, against a minute or more to pull the 9 GB espressif/idf image). docker: the espressif/idf image through espressif/esp-idf-ci-action, as before. |
max_dec_total |
string | 0 |
Maximum total dec size in bytes for size budget enforcement (0 to disable) |
Jobs and permissions¶
| Job | Runs | Permissions |
|---|---|---|
generate-matrix |
always | contents: read |
build |
once per matrix entry, fail-fast: false, 30 min limit |
contents: read |
size-report |
pull requests only | pull-requests: write |
generate-matrixchecks out with submodules, finds the project tools (below), runsgenerate_matrix.pyand outputs the matrix.buildbuilds every build type of one app and IDF version (group_build_types): it checks out, restores the pip and compiler (ccache) caches (skipped withclean_build) and installs the tools'requirements.txt. Withidf_install: native(default) it resolves the IDF version to a commit, restores~/esp-idfand~/.espressiffor the matrix target from the cache keyed by that commit (or clones the IDF and runsinstall.sh <target>once when the key is new), installs a pinned, hash-checked ccache and runsbuild_app.shfor each build type. Withidf_install: dockerit frees runner disk space when short, pullsespressif/idf:<version>(4 attempts, 10 / 30 / 60 s apart) and runsbuild_app.shinside the image withespressif/esp-idf-ci-action. Either way it uploads the build folders.
Measured on driver-pcal9555 (Debug and Release of one app): native, warm cache, 93 s per job; native, new IDF
commit, about 190 s; docker with a warm ccache, 175 s. The image is 9.4 GB for every target; the native cache
holds one target, about 1.1 GB.
- size-report downloads every fw-* artifact, writes a size table from size.info / size.txt, comments
it on the pull request and enforces max_dec_total when it is not 0.
The caller grants the union: contents: read and pull-requests: write. See the
permissions contract.
Finding the project tools¶
The generate-matrix job needs generate_matrix.py, build_app.sh and config_loader.sh from
espidf-tools. It looks, in this order:
| Case | Path used |
|---|---|
project_tools_dir set |
That path; the job fails if it does not exist (no clone) |
project_tools_dir empty and <project_dir>/espidf-tools exists |
That folder |
| Otherwise | espidf-tools at the repository root, cloned from main (depth 1) when it is missing and auto_clone_tools is true |
A submodule is the reproducible choice: the clone follows the tools' main branch.
The matrix¶
generate_matrix.py reads app_config.yml and emits one entry per app, ESP-IDF version and build type:
app_config.yml |
Effect |
|---|---|
metadata.idf_versions |
ESP-IDF branches or tags, for example release/v5.5; default release/v5.5 |
metadata.build_types |
One list per IDF version, by index: [["Debug", "Release"], ["Debug"]] |
metadata.target |
Chip passed to the build, default esp32c6 |
apps.<name>.idf_versions, apps.<name>.build_types |
Per-app overrides; a flat build_types list applies to every version |
apps.<name>.ci_enabled: false |
Leaves the app out of CI |
ci_config.exclude_combinations |
Entries whose keys all match are dropped, for example {app_name: x, build_type: Release} |
Where app_config.yml is found
The workflow runs generate_matrix.py without --project-path, so the script looks for
examples/esp32/app_config.yml from the repository root, then for app_config.yml in the folder above the
script. Keep the project in examples/esp32, or keep the tools inside the project folder, so both point at
the same file.
Artifacts¶
Each build uploads <project_dir>/build* as fw-<app_name>-<idf_version_docker>-<build_type>, for example
fw-gpio_test-release-v5.5-Debug, kept for 7 days. build_app.sh writes size.info and size.txt into the
build folder; the size report reads them. The upload runs even when the build fails, so a failed build's logs are
in the artifact.
Size report and budget¶
On pull requests the size-report job comments a table with one row per build (app, IDF, target, build type and
the idf.py size summary). Set max_dec_total to a byte count to fail the job when any build's total dec
size is larger; 0 turns the check off.
When it fails¶
| Symptom | Cause | Fix |
|---|---|---|
startup_failure, no job ran |
The calling job grants less than contents: read, pull-requests: write |
Add the permissions to the calling job |
Project tools directory not found |
project_tools_dir points at a missing folder, or the submodule was not added |
Add the submodule, or leave project_tools_dir empty to clone |
Required script ... not found |
The tools folder is not espidf-tools, or is an old copy | Update the submodule |
Configuration file not found |
No app_config.yml where generate_matrix.py looks (see the warning above) |
Move the project to examples/esp32 or the tools into the project |
Could not pull espressif/idf:... after 4 attempts |
Docker Hub outage, or an IDF version with no image | Check the version name; start a new run |
No build directory found! |
build_app.sh failed before creating build* |
Read the build step log; reproduce locally with build_app.sh |
| Size budget exceeded | A build's dec total is above max_dec_total |
Shrink the firmware or raise the budget |
| A fix here does not apply | "Re-run failed jobs" reuses the workflow revision of the first run | Start a new run (see Versioning) |
Next: ru-release-firmware, which ships these artifacts.