feat(gha): Auto-publish releases

- GHA release workflow is updated to use an action for uploading all assets. The action docs say it updates a release if one already exists, and since this triggers on release and we pass a release tag we know the release already exists. - GHA release candidate workflow is updated to auto-publish a pre-release release on push to a `release/**` branch. A script is added and used to generate a release message made up of the commits since the last release of any kind. - ACT profiles are added to allow locally testing these workflows without needing to push and wait for GHA to run. - Docs are updated to note how to test the workflows locally.
2026-04-23 22:48:41 -04:00
parent 5d0620bc3a
commit 0010b200ed
7 changed files with 423 additions and 47 deletions
@@ -27,6 +27,7 @@ pio run
 CI enforces formatting, static analysis, and build checks.
 Use clang-format 21+ locally to match CI.
 If `clang-format` is missing or too old locally, see [Getting Started](./getting-started.md).
+If your change affects release automation, also dry-run the release workflows locally with `act` before opening the PR. See [Testing and Debugging](./testing-debugging.md#test-release-workflows-locally-with-act).

 ## 4) Open the PR

@@ -34,6 +34,99 @@ python3 -m pip install pyserial colorama matplotlib
 python3 scripts/debugging_monitor.py
 ```

+## Test release workflows locally with `act`
+
+Use [`act`](https://github.com/nektos/act) to dry-run the release workflows
+after modifying them. Running locally with `act` is faster and more iterative
+than pushing commits to GitHub and waiting for Actions to run. It will test the
+entire workflow, including job conditions and release-notes generation, without
+actually publishing releases or uploading assets.
+
+For this repository, local `act` runs simulate different GitHub event types for
+the two release workflows:
+
+- `release.yml` is exercised with a simulated `release` event whose action is
+  `published`
+- `release_candidate.yml` is exercised with a simulated `push` event on
+  a `release/**` branch
+
+### What local `act` runs validate
+
+Local runs are useful for validating:
+
+- workflow wiring and job conditions
+- PlatformIO release builds
+- release-notes generation via `scripts/generate_release_notes.py`
+
+Local `act` runs do **not** publish GitHub releases or upload release assets.
+Those steps are skipped when `ACT=true`, so final release publication still
+requires a real GitHub Actions run.
+
+### Prerequisites
+
+- `act` installed locally
+- Docker available and running
+  - Podman will most likely also work. Ensure the rootless user socket is
+    configured and set `DOCKER_HOST` to its path (e.g.
+    `export DOCKER_HOST=unix:///run/user/1000/podman/podman.sock`).
+- `gh` CLI authenticated (`gh auth status`)
+- event payload files in `.github/act/`
+
+Included payload files:
+
+- `.github/act/release-published.json` to simulate the `release.published` event
+  used by `release.yml`
+- `.github/act/release-candidate-push.json` to simulate the branch-push event
+  used by `release_candidate.yml`
+
+### Provide `GITHUB_TOKEN` safely
+
+Release-notes generation expects `GITHUB_TOKEN`. Prefer exporting it from `gh`
+instead of pasting a token directly into shell history:
+
+```sh
+export GITHUB_TOKEN="$(gh auth token)"
+```
+
+Then pass it to `act` by name:
+
+```sh
+act ... -s GITHUB_TOKEN
+```
+
+Unset it when finished:
+
+```sh
+unset GITHUB_TOKEN
+```
+
+### Run the stable release workflow locally
+
+```sh
+act release \
+  -W .github/workflows/release.yml \
+  -e .github/act/release-published.json \
+  -s GITHUB_TOKEN
+```
+
+### Run the release-candidate workflow locally
+
+```sh
+act push \
+  -W .github/workflows/release_candidate.yml \
+  -e .github/act/release-candidate-push.json \
+  -s GITHUB_TOKEN
+```
+
+### What still needs a real GitHub run
+
+After a local `act` pass, a real GitHub Actions run is still required to verify:
+
+- GitHub release creation
+- asset upload
+- workflow permissions and repository-token behavior
+- the exact GitHub-hosted runner environment
+
 ## Useful bug report contents

 - Firmware version and build environment