release - SKILL.md Agent Skill

name: release description: >- Create and publish a new GitHub release for this repository, then verify that the related GitHub Actions firmware release build starts. Use when the user says "/release", "make a release", "create a GitHub release", "publish a release", "tag a release", "major release", "feature release", "minor release", "patch release", "start the release action", or wants firmware release assets generated by GitHub Actions.

GitHub Release

Create a GitHub release from main and confirm the Build Release action starts. 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. Verify the Release Action Started

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:

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

If no release event run appears after a short wait, do not silently switch to manual dispatch. Report that the release was created but the automatic action was not found.

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 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 Release run URL and current result
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