Skip to content

ru-release-firmware

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.

File: .github/workflows/ru-release-firmware.yml

It replaces ru-release-with-artifacts, with the same inputs and behaviour. The difference is one permission: its job asks for actions: read as well as contents: write, so it can find the tagged commit's CI run in a private repository.

Caller

---
name: Release
on:
  push:
    tags: ["v*"]

jobs:
  release:
    uses: kokeb-labs/ci-tools/.github/workflows/ru-release-firmware.yml@v1
    permissions:
      actions: read
      contents: write
    with:
      build_workflow: esp32-examples-build-ci.yml
      fail_on_no_artifacts: true

Grant both permissions. A caller that grants only contents: write gets startup_failure.

Release only after CI passed on the tag

Triggered by the tag push itself, the release runs at the same time as CI on that tag and can publish before (or without) a green build. Trigger it from the finished CI run instead, and pass the tag and the commit:

on:
  workflow_run:
    workflows: [CI]
    types: [completed]

permissions:
  actions: read
  contents: write

jobs:
  release:
    if: >-
      github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.event == 'push' &&
      startsWith(github.event.workflow_run.head_branch, 'v')
    uses: kokeb-labs/ci-tools/.github/workflows/ru-release-firmware.yml@v1
    with:
      build_workflow: ci.yml
      tag_name: ${{ github.event.workflow_run.head_branch }}
      commit: ${{ github.event.workflow_run.head_sha }}
      fail_on_no_artifacts: true

The workflow checks that the tag points to commit before it releases anything.

Move from ru-release-with-artifacts

Change two lines in the calling workflow: the file name in uses:, and actions: read next to contents: write in its permissions. The inputs are the same, so with: stays as it is.

jobs:
  release:
    uses: kokeb-labs/ci-tools/.github/workflows/ru-release-firmware.yml@v1   # was ru-release-with-artifacts.yml
    permissions:
      actions: read                                                          # new
      contents: write

Inputs

Input Type Default Description
build_workflow string esp32-examples-build-ci.yml Name of the ESP32 build workflow
artifact_pattern string fw-.* Pattern for firmware artifacts
draft boolean false Create as draft release
prerelease boolean false Mark as pre-release
tag_name string empty Tag name for release (defaults to github.ref_name)
fail_on_no_artifacts boolean false Fail if no firmware artifacts found
commit string empty Commit whose CI artifacts are released, and that the release tag must point to. Empty: github.sha. A caller triggered by workflow_run passes github.event.workflow_run.head_sha, because github.sha is then the default branch's head, not the tagged commit.

Jobs and permissions

One job, release, with actions: read and contents: write. It checks out with full history, downloads every artifact whose name matches artifact_pattern from the run of build_workflow on commit (default github.sha) (dawidd6/action-download-artifact), builds the release files with tools/release_assets/release_assets.py from ci-tools at the same commit as this workflow, and creates the release for tag_name (default: the pushed tag) with generated notes and those files attached (softprops/action-gh-release). The checksums also go to the run's summary.

Permission What needs it
contents: write Creating the release and uploading its files
actions: read Listing the build workflow's runs to find the tagged commit's run, and downloading its artifacts. A public repository allows both reads without it; a private one refuses them with Resource not accessible by integration

What the release holds

For tag v1.2.0 of a repository whose driver.yml names it as5047u:

File What it is
as5047u-1.2.0.tar.gz The tagged tree (git archive), compressed with a fixed date: the same tag always gives the same bytes. GitHub's own "Source code" archives are not promised to be byte-stable, so checksums name this one. Submodules are not inside; the SBOM names each at its pinned commit.
as5047u-1.2.0.spdx.json SBOM, SPDX 2.3 JSON: the repository as the main package (licence from LICENSE, the archive's SHA-256, the tagged commit), each git submodule as a package it contains (URL and pinned commit), and each firmware zip as a file generated from it.
fw-<app>-<idf>-<type>.zip One per firmware artifact: for each ESP-IDF build in it, flasher_args.json, flash_args, every file they flash (bootloader, partition table, app) and the app's .elf and .map, at their build paths. An artifact with no flasher_args.json is zipped whole, with a warning.
SHA256SUMS SHA-256 of every other file, in sha256sum -c format.

One zip per artifact keeps Debug and Release apart. Uploading the build folders file by file, as versions before 1.7.0 did, attached thousands of files (an ESP-IDF build folder holds about 1,500), let files with the same name in Debug and Release overwrite each other, and could pass GitHub's limit of 1,000 files per release.

Check a download

gh release download v1.2.0 -R kokeb-labs-drivers/driver-as5047u -D v1.2.0
cd v1.2.0 && sha256sum -c SHA256SUMS        # macOS: shasum -a 256 -c SHA256SUMS

Every line must say OK. To flash a firmware zip: unzip it, go to the build folder inside and run esptool.py --chip <chip> write_flash @flash_args (the chip is in flasher_args.json).

Provenance

For a public repository, add ru-attest-release as a job after this one. It signs build provenance for every file in SHA256SUMS, and gh attestation verify checks a download against it. It is a separate workflow because it needs id-token: write and attestations: write, which callers of this workflow do not grant.

When it finds no firmware

The release only reuses artifacts; it never builds. It finds none when:

  • the build workflow has not run on the tagged commit (tag a commit that was pushed to a branch the build runs on, and wait for that build to finish);
  • the artifacts expired (ru-build keeps them 7 days);
  • build_workflow names a different file than the caller of ru-build;
  • artifact_pattern (a regular expression, default fw-.*) does not match.

With fail_on_no_artifacts: false (the default) the release is still created, without firmware, and the step logs a warning. Set it to true to fail instead.

When it fails

Symptom Cause Fix
startup_failure The calling job does not grant contents: write and actions: read Grant both in the calling job, or at the top of the calling workflow
Resource not accessible by integration - .../rest/actions/workflow-runs#list-workflow-runs-for-a-workflow in the download step The token cannot read workflow runs: the caller still calls ru-release-with-artifacts, or the repository restricts the workflow token Call this workflow with actions: read granted; check Settings > Actions > Workflow permissions
Resource not accessible by integration when creating the release The repository restricts the workflow token to read Grant contents: write in the caller; check Settings > Actions > Workflow permissions
Release has no firmware zips See above Set fail_on_no_artifacts: true to catch it
release files share a name Two artifacts would give zips with the same name Give the artifacts distinct names (ru-build names them by app, IDF version and build type)
flasher_args.json lists files the artifact lacks The build artifact was uploaded without part of the build Upload the whole build folder in ru-build
tag ... points to ..., not to the released commit The tag names another commit than commit (default github.sha) Pass the tagged commit as commit, or tag the commit CI built
tag ... does not exist here The release ran for a tag that was not pushed Push the tag first

Next: ensure-tools-directory, for your own jobs that need the project tools.