release

# 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. ```bash 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: ```bash 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: ```text 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: ```text 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: ```bash 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: ```bash TAG="vX.Y.Z" gh release create "$TAG" \ --target main \ --generate-notes \ --fail-on-no-commits ``` Pre-release: ```bash 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: ```bash 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. ```bash 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: ```bash 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: ```bash 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: ```bash gh release view "$TAG" \ --json tagName,url,isPrerelease,assets \ --jq '{tagName, url, isPrerelease, assets: [.assets[].name]}' ``` Expected release assets: ```text immich-frame.factory.bin immich-frame.ota.bin immich-frame.manifest.json immich-frame-v2.factory.bin immich-frame-v2.ota.bin immich-frame-v2.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: ```bash 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 Release` run 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.