Skip to content

ru-release-with-artifacts

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.

File: .github/workflows/ru-release-with-artifacts.yml

Fails in private repositories

Its job asks only for contents: write. In a private repository that token cannot list the build workflow's runs, and the release fails in the download step with Resource not accessible by integration. Asking for actions: read here would break every caller that grants only contents: write, so ru-release-firmware asks for it instead. This workflow keeps working for its existing callers until the next major, which removes it.

Move to ru-release-firmware

Change the file name in uses: and grant actions: read next to contents: write. The inputs are the same.

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

Caller (existing)

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

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

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:
  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-with-artifacts.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.

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 contents: write. It checks out with full history, downloads every artifact whose name matches artifact_pattern from the run of build_workflow on 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.

The workflow does not ask for actions: read, because existing callers grant only contents: write and would hit startup_failure. Without it the token can list workflow runs and download their artifacts only in a public repository. A private repository refuses those reads with Resource not accessible by integration; use ru-release-firmware there.

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 Grant it in the calling job
Resource not accessible by integration - .../rest/actions/workflow-runs#list-workflow-runs-for-a-workflow in the download step The repository is private, and this workflow's token has no actions: read Move to ru-release-firmware and grant actions: read
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 ... does not exist here The release ran for a tag that was not pushed Push the tag first

Next: ru-release-firmware, which replaces this workflow.