GitHub Release
Create a GitHub release from main and wait for the Build Release action to
complete successfully. Do not report the release as successful while the
workflow is queued or in progress. In this repo, publishing a release is the
normal way to start the firmware build because .github/workflows/release.yml
uploads firmware assets only for the release event.
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. Create the Release
Before publishing, run the compile-aware release-readiness check:
npm run check:release-ready-with-compile
Use a published release, not a draft, so GitHub emits the release.published
event and starts the firmware build.
Stable release:
TAG="vX.Y.Z"
gh release create "$TAG" \
--target main \
--generate-notes \
--fail-on-no-commits
Pre-release:
TAG="vX.Y.Z-beta.N"
gh release create "$TAG" \
--target main \
--generate-notes \
--fail-on-no-commits \
--prerelease \
--latest=false
If a draft release already exists for the tag and the user wants to publish it, publish the draft instead of creating a duplicate:
gh release edit "$TAG" --draft=false
Do not close GitHub issues as part of this workflow unless the user explicitly asks; they prefer to test before issues are closed.
4. Wait for and verify the Release Action
The related action is Build Release in .github/workflows/release.yml.
Publishing the release should start it automatically.
gh run list \
--workflow release.yml \
--event release \
--limit 10 \
--json databaseId,status,conclusion,createdAt,headBranch,displayTitle,url
Find the newest run for the release tag, then watch it to completion:
gh run watch <run-id> --exit-status
The release workflow is not complete until gh run watch exits successfully.
If the run is queued or in progress, report that state and keep waiting. If it
fails, report the failed run and relevant job or log details; do not report
success and do not silently switch to manual dispatch.
If no release event run appears after a short wait, report that the release
was created but the automatic action was not found. Do not silently switch to
manual dispatch.
Manual dispatch is only a test-build fallback:
gh workflow run release.yml --ref "$TAG"
Warn the user before using this fallback because workflow-dispatched runs produce an artifact but do not upload firmware files to the GitHub release.
5. Verify Outputs After a Successful Build
Only after Build Release succeeds, confirm the release has the expected
assets:
gh release view "$TAG" \
--json tagName,url,isPrerelease,assets \
--jq '{tagName, url, isPrerelease, assets: [.assets[].name]}'
Expected release assets:
immich-frame.factory.bin
immich-frame.ota.bin
immich-frame.manifest.json
immich-frame-7inch.factory.bin
immich-frame-7inch.ota.bin
immich-frame-7inch.manifest.json
The release workflow verifies the compiled binaries before upload, downloads the uploaded assets from GitHub Releases, and verifies them again. The checks confirm that the manifests, OTA checksums, release URLs, and embedded ESPHome project versions all match the release tag.
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 docs.yml --event workflow_run --limit 5
That workflow downloads the latest release assets, publishes the public firmware URLs used by the installer and OTA updater, and verifies those URLs after GitHub Pages deploys.
Report Back
Summarize in plain language:
- Release tag and GitHub release URL
Build Releaserun URL and final result- Whether the expected firmware assets are attached and verified
- Any docs deployment run URL if checked
- Any action needed from the user, especially if the release build failed or remains incomplete
Never say that a release succeeded merely because the GitHub release was
created or the Build Release action started. Report success only after the
workflow completes successfully and the expected assets are verified.
