| name | release |
| description | Cut a new release of git-workset — pick the version, tag, push, and verify the automated workflow. Use when the user asks to release, ship, or cut a version. |
Release Workflow
The release is fully automated once you push a v*.*.* tag: .github/workflows/release.yml builds binaries for six targets, generates release notes, publishes the GitHub Release, deploys the marketing page, and updates the Homebrew tap. Your job is to bump the version, tag correctly, and verify the workflow finished cleanly.
1. Verify the starting state
git fetch --tags origin
git status
git log --oneline $(git describe --tags --abbrev=0)..HEAD
The log above shows what's going into the release. If it's empty, there's nothing to release.
Also confirm the latest CI run on main is green — if main is broken, don't release from it.
2. Pick the version (semver)
Read the unreleased commits from step 1 and pick the smallest correct bump:
- Any
feat: commits → minor bump (0.x.0 → 0.(x+1).0)
- Only
fix:/perf:/etc. → patch bump (0.x.y → 0.x.(y+1))
- Any breaking change → major bump (this project is pre-1.0, so call this out explicitly to the user before doing it)
If unsure, state your reasoning and the proposed version, then proceed.
3. Bump Cargo.toml and regenerate Cargo.lock
cargo check
Both files must be staged together — a mismatched lockfile causes CI noise.
4. Commit the bump
Ideally the version bump rides along with the feat:/fix: commit that introduces the change (see AGENTS.md). When releasing after-the-fact (commits already pushed), use a separate commit:
git commit -m "chore: bump version to 0.X.Y"
The release-notes generator filters chore: lines, so this commit won't pollute the notes.
If you're also tweaking release tooling (workflow files, this skill, AGENTS.md) bundle those into the same chore: commit — it keeps history tidy.
5. Push main and wait for CI
git push origin main
gh run watch
CI must be green across all platforms (ubuntu, macOS, Windows) before tagging. Don't tag a red commit.
6. Create the annotated tag and push it
git tag -a v0.X.Y -m "v0.X.Y"
git push origin v0.X.Y
Annotated (-a), not lightweight — the workflow and tooling expect tags with metadata.
Pushing the tag triggers .github/workflows/release.yml.
7. Watch the release workflow
gh run watch $(gh run list --workflow Release --limit 1 --json databaseId -q '.[0].databaseId') \
--repo lauripiispanen/git-workset
The workflow has these jobs (in dependency order):
| Job | What it does |
|---|
test | Runs cargo test on ubuntu |
build (×6) | Compiles for linux x86/arm, windows x86/arm, macOS x86/arm; produces .tar.gz/.zip + .sha256 |
release | Collects artifacts, generates notes from <prev-tag>..<new-tag> (filters chore:/ci:/docs:/test:/bump lines), publishes the GitHub Release |
deploy-pages | Stamps the version into the marketing page and pushes to gh-pages |
deploy-homebrew | Renders Formula/git-workset.rb with the six sha256s and version, pushes to lauripiispanen/homebrew-tap |
All must be green. The Homebrew tap update is automatic — do not do it manually.
The historically-fragile target is aarch64-unknown-linux-gnu (uses cross). If a build fails, see step 9.
8. Verify the release
After the workflow goes green:
gh release view v0.X.Y --repo lauripiispanen/git-workset
Check:
- All six binaries + six
.sha256 files are attached
- Release notes contain the expected
feat:/fix: lines, no chore:/ci:/docs:/test: noise
- Tap formula updated:
gh api repos/lauripiispanen/homebrew-tap/commits/main -q .commit.message should mention the new tag
Optionally smoke-test:
brew update && brew upgrade git-workset
git workset --version
9. If something fails
The tag is what triggers the workflow, so recovering means deleting the tag, fixing the issue, and retagging:
git push --delete origin v0.X.Y
git tag -d v0.X.Y
git tag -a v0.X.Y -m "v0.X.Y"
git push origin v0.X.Y
If a GitHub Release was already created before the failure, delete it too:
gh release delete v0.X.Y --yes
Don't try to "rerun the workflow" from the GitHub UI without deleting the tag first — softprops/action-gh-release will refuse to overwrite an existing release.
Out of scope
This skill does not handle code changes or feature work. Use the implement skill for that — it includes a version-bump step so that, ideally, by the time you reach release the version is already correct and step 3 is a verification rather than an edit.
