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. Verify Release Source Readiness

No preparation PR is required. The Build Release workflow reads the published release catalogue, adds the selected tag to the compatibility list in its private checkout, rebuilds and verifies the web asset manifest, and carries the result through the release jobs. The Pages workflow performs the same catalogue-based preparation for ordinary public docs builds and deploys the verified release artifact when it follows a successful release workflow.

Set the selected tag before creating the draft, for example:

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

Keep the source checkout clean and make sure generated outputs are current before creating the tag. The compatibility 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