release
/release
Ship a new version of the Codealong Mac app. Picks the version, writes the release notes, tags it so GitHub builds, signs and notarizes it, checks the draft as a download gets it, and publishes it once the user says so; installed copies, the website's Download and the Homebrew cask then follow by themselves. Use when the user says they're ready to release, wants a new version out, or runs /release (optionally with a version, /release 0.4.0).
- Author
- codealong ↗
- Repository
- codealong ↗
- Licence
- Apache-2.0
- Last repository change
- 27.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 3
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
What it does and when to use it
Ship a new version of the Codealong Mac app. Picks the version, writes the release notes, tags it so GitHub builds, signs and notarizes it, checks the draft as a download gets it, and publishes it once the user says so; installed copies, the website's Download and the Homebrew cask then follow by themselves. Use when the user says they're ready to release, wants a new version out, or runs /release (optionally with a version, /release 0.4.0).
Original author description
Ship a new version of the Codealong Mac app. Picks the version, writes the release notes, tags it so GitHub builds, signs and notarizes it, checks the draft as a download gets it, and publishes it once the user says so; installed copies, the website's Download and the Homebrew cask then follow by themselves. Use when the user says they're ready to release, wants a new version out, or runs /release (optionally with a version, /release 0.4.0).
How it works
- 1. Where things stand
- 2. The version and the notes
- 3. Tag it
- 4. The build
- 5. Check the draft
- 6. Publish, when the user says so
- 7. Say how it went
SKILL.md preview
---
name: release
description: Ship a new version of the Codealong Mac app. Picks the version, writes the release notes, tags it so GitHub builds, signs and notarizes it, checks the draft as a download gets it, and publishes it once the user says so; installed copies, the website's Download and the Homebrew cask then follow by themselves. Use when the user says they're ready to release, wants a new version out, or runs /release (optionally with a version, /release 0.4.0).
---
# Release
A release is a version tag on `main`. `scripts/version.sh` makes it: it sets the one version the
app, the `codealong` command and the Claude Code plugin share, commits "Release x.y.z" and tags it
with the release notes as the tag's message. Pushing the tag has GitHub build the release
(`.github/workflows/release.yml`): universal, signed with the Developer ID, notarized, with the
signed update and `latest.json`, as a draft release. Publishing the draft is what makes it live:
installed copies find it (their updater reads `releases/latest/download/latest.json`), the
website's Download buttons follow `releases/latest`, and `.github/workflows/homebrew.yml` points
the cask in `codealong/homebrew-tap` at it. `design/plans/releases.md` has the decisions behind
all of it.
Everything a release does is public and can't be taken back once people have it. The user says
go at four points, in chat, and you never go past one without it:
1. the version and the notes, before the tag is pushed;
2. the build, which waits for their approval on GitHub (the `release` environment's reviewer);
3. publishing the draft;
4. deleting or moving any tag or release.
## 1. Where things stand
```bash
git fetch -q origin
git describe --tags --abbrev=0 origin/main # the last version tag
gh release list -R codealong/codealong --limit 5 # drafts waiting, the latest published
git rev-parse origin/main # the commit the release will tag
gh run list -R codealong/codealong --workflow linux.yml --branch main --limit 1 --json headSha,status,conclusion,url # main's last Linux check
```
Say what's there: the last release and whether it's published, any draft still waiting (a draft
older than `main` is stale: offer to delete it, with its tag, once the new one is out), and
whether `main` is green. Something already wrong on `main` is fixed and landed first, the usual
way (CLAUDE.md's *Landing work*), not in the release.
Linux is checked only every four hours (`linux.yml`), and no Mac can check it, so its last run is
often of an older commit than the one being released. A release needs a run that passed on the
commit it's made from: when the last run's `headSha` isn't `origin/main`'s, start one (`gh
workflow run linux.yml -R codealong/codealong --ref main` prints its link, which ends in its id)
and wait for it in the background (`gh run watch <id> -R codealong/codealong --exit-status`)
while you write the notes. It takes about three minutes, twenty when its cache is cold; the
four-hourly run cancels one still going on `main`, and is then the one to wait for. One that
fails is fixed and landed like anything else wrong on `main`, and checked again on the commit
with the fix.
## 2. The version and the notes
The version is `x.y.z`: while it's 0.x, a minor version when there are features, a patch when
there are only fixes; `x.y.z-beta.n` for a prerelease, which GitHub marks as one, so publishing it
moves neither `latest` (installed copies) nor the cask. It must be newer than the app's
(`src-tauri/tauri.conf.json`), and a version is never used twice. Take the one the user gave, or
propose one.
Write the notes from what changed since the last tag:
```bash
git log --no-merges --format='%h %s' <last tag>..origin/main
gh release view <last tag> -R codealong/codealong --json body --jq .body # the last notes, for their shape
```
Commit subjects here are long feature sentences; the notes are for people using the app, not
for the repo. Leave out "Release …" commits, "After Codex's review" follow-ups (they're part of
the feature before them), docs, tests, previews and refactors nobody can see. Then, in a file in
your scratchpad:
- a first line that says what this version is about, in a sentence;
- **What's new**: one bullet per feature, a short phrase first and then what it does, plain words
and sentence case, the biggest first;
- **Fixes**, when there are any worth naming;
- for the first public release only, an **Install** section: the disk image from the release
page, or `brew install --cask codealong/tap/codealong`.
The notes go on the release page and in `latest.json`, which the app shows beside Restart when it
offers the update, so keep them to what a user would care about. They're public: no names from
the owner's other work or this Mac's real projects, people or sessions (the pre-push hook checks
commits, not the tag's message, so this is on you).
Show the user the version and the notes, and change them until they say go.
## 3. Tag it
From a worktree of its own at `origin/main`, never the main checkout, which other sessions'
uncommitted edits may be in (`version.sh` refuses to run anywhere HEAD isn't `origin/main` or
something's uncommitted):
```bash
git worktree add --detach ../codealong-release-<version> origin/main
cd ../codealong-release-<version>
git rev-parse HEAD # the commit Linux passed on in step 1
scripts/version.sh <version> --notes <notes file> --push
```
When `main` has moved past the commit Linux passed on, check the new one as step 1 does before
running `version.sh`, which makes the release from whatever `origin/main` is.
It commits "Release <version>", tags `v<version>`, and pushes the commit to `main` and then the
tag. When the push of the commit is turned away because `main` moved, nothing reached GitHub:
the tag is `version.sh`'s own, only in this worktree, and goes with it (`git tag -d v<version>`;
the rule about tags is for ones GitHub has), and this step starts again from a fresh worktree.
When the commit went and the tag didn't, push the tag: `git push origin v<version>`. Once the
tag is pushed, from the main checkout:
```bash
scripts/catch-up-main.sh
git worktree remove ../codealong-release-<version>
```
## 4. The build
```bash
git rev-parse 'v<version>^{commit}'
gh run list -R codealong/codealong --workflow release.yml --branch v<version> --event push --json databaseId,url,status,headSha
```
The run is the one for the tag (a tag's push is its branch here) whose `headSha` is the tagged
commit; it can take a minute to appear, so look again rather than take another release's run.
It waits for the user's approval before it starts ("Review deployments" on its page). Give
them the run's link and ask them to approve it there. Approve it yourself only when they tell you
to in chat, as them, through
`gh api repos/codealong/codealong/actions/runs/<id>/pending_deployments`
(POST `environment_ids[]` from a GET of the same, `state=approved`, a comment).
Once approved it takes about half an hour, most of it Apple's notarization. Wait for it in the
background (`gh run watch <id> -R codealong/codealong --exit-status`). When it fails:
- `gh run view <id> -R codealong/codealong --log-failed` says where.
- A step that timed out or Apple's service turning a request away is worth one rerun:
`gh run rerun <id> -R codealong/codealong --failed`.
- A fault in the build or the code is fixed and landed the usual way; the tag then names a
commit without the fix, so the release goes out as the next version (a tag is never moved
without the user's word).
- With GitHub's runners down, the same release builds on a Mac with the keys:
`scripts/release.sh --draft` from the tagged commit, with the keys from 1Password
(`design/plans/releases.md`).
## 5. Check the draft
```bash
scripts/check-release.sh <version>
```
It downloads the draft as GitHub serves it, marks it as downloaded the way a browser does, and
checks every file, Gatekeeper and notarization, the signature and entitlements, the version, the
license files, and the update and `latest.json`. Every line must be ok.
What it can't check is a person opening it: the first-open prompt, the setup wizard on a first
run, the permission prompts. The routine (`design/plans/releases.md`) has the user install the
draft on a Mac or user account that has never had Codealong before it's published: give them the
disk image (`gh release download v<version> -R codealong/codealong -p Codealong.dmg -D
<scratchpad>`) and ask how it went, or have them say they're publishing without trying it, and
say which in step 7. On a Mac that also runs Codealong Dev, opening the release quits Dev: they
share their settings, and the last one opened wins.
## 6. Publish, when the user says so
```bash
gh release edit v<version> -R codealong/codealong --draft=false --latest
```
A prerelease is published with `--prerelease` and without `--latest`, and then only its own page
changes: `latest.json` and the website's Download stay on the last release, and homebrew.yml's run
skips it by design, leaving the cask where it was. Check those stayed put. A release goes
everywhere; check that it did:
```bash
curl -sL https://github.com/codealong/codealong/releases/latest/download/latest.json | jq -r .version # installed copies
curl -sI https://www.codealong.com/api/update/darwin/aarch64/0.0.0 | grep -i '^location' # where they ask first: redirects to that latest.json (a HEAD isn't counted)
curl -sIL -o /dev/null -w '%{http_code}\n' https://github.com/codealong/codealong/releases/latest/download/Codealong.dmg # the website's Download: 200
gh run list -R codealong/codealong --workflow homebrew.yml --limit 1 # moved the cask
gh api repos/codealong/homebrew-tap/contents/Casks/codealong.rb --jq .content | base64 -d | grep -E '^ (version|sha256)'
```
The cask's `version` is the new one and its `sha256` the disk image's (`Codealong_<version>_universal.dmg.sha256`).
For a release (not a prerelease), a Homebrew run that skipped or failed leaves the cask on the
last version: its log says why, and
`gh workflow run homebrew.yml -R codealong/codealong --ref v<version>` runs it again (on the
tag: it takes the release from the ref it runs on, and its environment only lets `v*` tags in).
## 7. Say how it went
The release page's link, what `check-release.sh` and the checks after publishing showed, whether
the user tried the draft on a fresh install or published without, and what nobody checked yet
(an installed copy taking the update). Then offer to delete a stale draft and its tag, if step 1
found one.
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · codealong/codealong | 100 | Apache-2.0 |
| josephfung/curia | 100 | MIT |
| max-sixty/worktrunk | 100 | MIT |
| gtapps/hermitd | 100 | MIT |
| gtapps/hermitd | 100 | MIT |
| anthony-chaudhary/fak | 100 | Apache-2.0 |
| tractorjuice/arc-kit | 100 | MIT |
| drvoss/everything-copilot-cli | 100 | MIT |
| sma1lboy/rove | 100 | MIT |
Database snapshot: 13.11.2026 · package version 578ee2f31945 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 2 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100release-lotion
Release the Lotion macOS notes app to GitHub using the lotion-release CLI tool. Use this skill whenever the user wants to publish a new version, create a release, ship an update, cut a build, push a release to GitHub, or update the appcast. Also use when they mention archiving,… - 100releasing-clickup-cli
Publishes a new version of clickup-cli to npm, updates Homebrew tap, writes release notes, and syncs the agent skill. Use when releasing a new version, bumping version, or verifying a release. - 100new-version
Releases a new version of the RightSubs APK — picks the number (semver), updates VERSION and CHANGELOG, commits, creates the vX.Y.Z tag and, when the user asks, pushes it so GitHub Actions builds, signs and publishes the release. Use when the user asks for a new version, a… - 100ship-release
Use when the user asks to release, ship, publish, cut or tag a version of a project ("release v0.2.0", "ship a patch", "bump and publish"). Bumps every version manifest, updates CHANGELOG and README badges, commits, lands it directly or through a pull request (pre-PR check,… - 90d2r-release
Ship a new version of a Diablo II Resurrected mod to players - bump the version, write the changelog in player wording, build and publish the release package with a single fail-fast script, verify the version is live, create release pages, and update the bug list. Use after a… - 100release-cli
Release a new version of the pd CLI. Runs tests, bumps version, creates git tag, and pushes to remote. Use when releasing a new CLI version.