Release

GitHub Release

Create a draft GitHub release from main, dispatch the Build Release action, and watch it build and verify the complete firmware distribution. The workflow uploads assets while the release is private and publishes it only after every asset has been checked.

Release Flow

1. Check Readiness

Use main unless the user explicitly asks for a different branch.

git status --short --branch
git fetch origin --tags --prune
git switch main
git pull --ff-only origin main
gh auth status

Do not create a release from uncommitted or unpushed local changes. If local changes are release-related, commit and push them first. If unrelated changes are present, explain that they block a clean release and ask how to proceed.

Check recent releases and tags before choosing the new version:

gh release list --limit 10
git tag --list 'v*' --sort=-v:refname | head -20

2. Choose the Version

Use long semantic version tags: vMAJOR.MINOR.PATCH.

Do not create short release tags such as v1.0 or v1.1. If the user gives a short tag, normalize it to the long form and confirm before publishing:

v1.0 -> v1.0.0
v1.1 -> v1.1.0

If the user gives a full tag like v1.2.3, use that exact tag. If the user asks for a release type instead of a tag, calculate the next version from the latest stable vX.Y.Z tag and confirm the calculated tag before publishing. Ignore pre-release tags such as v1.2.3-beta.1 when choosing the stable base.

Version bump rules:

major            v1.2.3 -> v2.0.0
feature or minor v1.2.3 -> v1.3.0
patch            v1.2.3 -> v1.2.4

If there is no existing stable release, treat the first stable release as v1.0.0 unless the user asks for a different full tag.

3. Prepare Web-Asset Compatibility

Before creating the tag, add it to the immutable web bundle's compatibility list. This makes the hosted bridge select the declared bundle for the new firmware instead of falling back to the editor embedded in the device.

Set the selected tag before preparing the bundle, for example:

# Stable release:
TAG="vX.Y.Z"
# Pre-release: TAG="vX.Y.Z-beta.N"

git switch -c "jtenniswood/prepare-web-assets-${TAG#v}"
python3 scripts/prepare_release_web_assets.py "$TAG"
python3 scripts/build.py
python3 scripts/build.py --check
npm run check:release-preflight
git add scripts/build.py docs/public/webserver
git commit -m "Prepare web assets for $TAG"
git push -u origin HEAD
gh pr create --base main --title "Prepare web assets for $TAG" --body "Adds $TAG to the declared immutable web bundle compatibility list."

Do this before tagging: the tag must point at the source revision that already declares its compatible web bundle. Have that preparation PR reviewed and merged, then return to main and pull the merged revision before creating the release tag. The helper retains dev, the five current stable releases, and the latest pre-release only.

4. Create the Tag and Draft Release

Push that exact release tag so every workflow job can check out one immutable source revision. Then create a draft release for the existing tag. Do not publish the draft manually: the workflow owns that final transition.

git tag -a "$TAG" -m "Release $TAG" origin/main
git push origin "$TAG"

Stable release:

gh release create "$TAG" \
  --verify-tag \
  --draft \
  --notes "Firmware is being built and verified. This draft will publish automatically when complete." \
  --fail-on-no-commits

Pre-release:

gh release create "$TAG" \
  --verify-tag \
  --draft \
  --notes "Firmware is being built and verified. This draft will publish automatically when complete." \
  --fail-on-no-commits \
  --prerelease \
  --latest=false

If a draft already exists, reuse it only after confirming it is still a draft and its tag exists on the remote:

git ls-remote --exit-code --tags origin "refs/tags/$TAG"
gh release view "$TAG" --json isDraft,tagName,url

Do not close GitHub issues as part of this workflow unless the user explicitly asks; they prefer to test before issues are closed.

5. Start and Watch the Release Action

Dispatch Build Release with the draft tag. Manual dispatch is the only supported release path because a draft release must remain private during the build.

gh workflow run release.yml --ref "$TAG" -f release_tag="$TAG"
gh run list \
  --workflow release.yml \
  --event workflow_dispatch \
  --limit 10 \
  --json databaseId,status,conclusion,createdAt,headBranch,displayTitle,url

Find the newest run for the release tag, then watch it:

gh run watch <run-id> --exit-status

If the workflow fails, the release should remain a draft. Report the failed job and do not publish it manually.

6. Verify Outputs

After Build Release succeeds, confirm the release is public and has the expected assets:

gh release view "$TAG" \
  --json tagName,url,isDraft,isPrerelease,assets \
  --jq '{tagName, url, isDraft, isPrerelease, assets: [.assets[].name]}'

Expected release assets:

esp32-p4-86.factory.bin
esp32-p4-86.manifest.json
esp32-p4-86.ota.bin
guition-esp32-p4-jc1060p470.factory.bin
guition-esp32-p4-jc1060p470.manifest.json
guition-esp32-p4-jc1060p470.ota.bin
guition-esp32-p4-jc1060p470-v2.factory.bin
guition-esp32-p4-jc1060p470-v2.manifest.json
guition-esp32-p4-jc1060p470-v2.ota.bin
guition-esp32-p4-jc4880p443.factory.bin
guition-esp32-p4-jc4880p443.manifest.json
guition-esp32-p4-jc4880p443.ota.bin
guition-esp32-p4-jc8012p4a1.factory.bin
guition-esp32-p4-jc8012p4a1.manifest.json
guition-esp32-p4-jc8012p4a1.ota.bin
guition-esp32-p4-jc8012p4a1-v2.factory.bin
guition-esp32-p4-jc8012p4a1-v2.manifest.json
guition-esp32-p4-jc8012p4a1-v2.ota.bin
guition-esp32-s3-4848s040.factory.bin
guition-esp32-s3-4848s040.manifest.json
guition-esp32-s3-4848s040.ota.bin

The Deploy Docs workflow is configured to run after a successful Build Release. Check it if the user asks about docs or firmware download availability:

gh run list --workflow pages.yml --event workflow_run --limit 5

Report Back

Summarize in plain language:

• Release tag and GitHub release URL
• Build Release run URL and current result
• Whether the verified draft was published and release notes were installed
• Whether the expected firmware assets are attached
• Any docs deployment run URL if checked
• Any action needed from the user, especially if a run failed