# Release

> 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.

- Skill: `jtenniswood/release-3` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add jtenniswood/release-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jtenniswood/release-3/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: jtenniswood (https://skillmd.com/u/jtenniswood)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/jtenniswood/release-3

---


# 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.

```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

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 \
  --notes "Detailed changelog will be added automatically by the Build Release workflow." \
  --fail-on-no-commits
```

Pre-release:

```bash
TAG="vX.Y.Z-beta.N"
gh release create "$TAG" \
  --target main \
  --notes "Detailed changelog will be added automatically by the Build Release workflow." \
  --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. Verify the Release Action Started

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:

```bash
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:

```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 `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
media-player-4848s040.factory.bin
media-player-4848s040.manifest.json
media-player-4848s040.ota.bin
media-player-jc1060p470.factory.bin
media-player-jc1060p470.manifest.json
media-player-jc1060p470.ota.bin
media-player-jc4880p443.factory.bin
media-player-jc4880p443.manifest.json
media-player-jc4880p443.ota.bin
media-player-jc8012p4a1.factory.bin
media-player-jc8012p4a1.manifest.json
media-player-jc8012p4a1.ota.bin
media-player-p4-86-panel.factory.bin
media-player-p4-86-panel.manifest.json
media-player-p4-86-panel.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:

```bash
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 automatic release notes update job ran
- 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

