github-releases

name	github-releases
description	Create releases for Rust CLI tools, macOS apps, Python/uv projects, and Next.js apps. Use when asked to release, tag, ship, publish, or deploy any project.
allowed-tools	Read, Edit, Bash, Grep, Glob, WebFetch

Release Workflows

Project-specific release workflows covering Rust CLI tools, macOS apps, Python/uv deployments, and Next.js apps.

Quick Reference: Which Workflow?

Project Type	Workflow	Trigger
Rust CLI (AllBeads, QDOS)	Tag-triggered CI	git tag -a vX.Y.Z → GitHub Actions builds binaries
macOS App (ethertext, AllBeadsApp)	Makefile-driven	make archive → notarize → make release
Python/uv (rookery)	CI Deploy	Push to main → tests pass → auto-deploy to EC2
Next.js (AllBeadsWeb)	Vercel	Push to main → auto-deploy

---

Rust CLI Release (AllBeads, QDOS)

Pre-Release Checklist

# Quality gates (ALL must pass)
cargo fmt -- --check && cargo clippy -- -D warnings && cargo test

# Check current version
grep '^version' Cargo.toml

# Verify clean working tree
git status

Release Process

1. Update version in Cargo.toml

   version = "X.Y.Z"
   

2. Commit version bump

   git add Cargo.toml Cargo.lock
   git commit -m "Bump version to X.Y.Z"
   

3. Create annotated tag (triggers CI release)

   git tag -a vX.Y.Z -m "AllBeads X.Y.Z Release
   
   ## Highlights
   - Key feature 1
   
   ## Changes
   - Change 1
   
   ## Bug Fixes
   - Fix 1"
   

4. Push to trigger release

   git push && git push --tags
   

5. Monitor release build

   gh run list --limit 3
   gh run watch <run-id>
   

6. Update release title/notes (optional)

   gh release edit vX.Y.Z --title "vX.Y.Z - Feature 1, Feature 2"
   

7. Update Homebrew tap (manual)

   # Get SHA256 for macOS binary
   curl -sL https://github.com/USER/REPO/releases/download/vX.Y.Z/binary-macos-aarch64 | shasum -a 256
   
   # Update homebrew-REPO/Formula/binary.rb
   # - Update version "X.Y.Z"
   # - Update sha256 hash
   cd ~/Workspace/homebrew-REPO
   git add . && git commit -m "Update to vX.Y.Z" && git push
   

GitHub Actions Workflow

The release workflow builds multi-platform binaries:

• Linux x86_64 (glibc + musl)
• Linux aarch64
• macOS x86_64 + aarch64
• Windows x86_64

Prerelease detection: tags containing alpha, beta, or rc are marked as prereleases.

---

macOS App Release (ethertext, AllBeadsApp)

Prerequisites

• Xcode with valid signing identity
• create-dmg installed: brew install create-dmg
• AWS CLI configured for S3 uploads
• Sparkle for auto-updates: brew install --cask sparkle

Release Process

1. Update version in Xcode

   • Set MARKETING_VERSION in project settings

2. Create Xcode archive

   make archive
   

3. Notarize in Xcode Organizer

   • Distribute App → Developer ID → Upload
   • Wait for notarization
   • Export notarized app to ~/Downloads/

4. Run release

   make release
   

   This:

   • Creates DMG from exported app
   • Uploads to S3 (versioned + latest)
   • Generates Sparkle appcast.xml
   • Updates Homebrew Cask

5. Commit and push

   git add -A && git commit -m "Release $(VERSION)" && git push
   make tag && git push --tags
   
   # Push homebrew tap
   cd ~/Workspace/homebrew-APPNAME
   git add -A && git commit -m "Update to $(VERSION)" && git push
   

Makefile Targets

Target	Description
make version	Show current version
make archive	Create Xcode archive
make dmg	Create DMG from exported app
make upload	Upload DMG to S3
make appcast	Generate Sparkle appcast.xml
make brew-update	Update Homebrew cask
make release	Full release (upload + appcast + brew)
make tag	Create git tag

Sparkle Setup (Auto-Updates)

make install-sparkle  # Install tools + generate keys
make sparkle-pubkey   # Show public key for Info.plist
make sparkle-sign     # Sign DMG for appcast

---

Python/uv Deploy (rookery)

Continuous deployment triggered by successful tests.

Deployment Flow

1. Push to main
2. GitHub Actions runs pytest
3. On success, triggers deploy workflow
4. SSH deploy to EC2:
   • Rsync files
   • uv sync dependencies
   • alembic upgrade head migrations
   • Restart systemd service
   • Health check (5 retries)

Manual Deploy

# Trigger deploy workflow manually
gh workflow run deploy.yml

Version Tracking

Deployments are stamped with build version:

printf "%s\n" "$(date -u +%Y%m%dT%H%M%SZ)_$(git rev-parse --short HEAD)" > VERSION

---

Next.js/Vercel Deploy (AllBeadsWeb)

Auto-deploy on push to main. No manual release process.

CI Workflow

bun install
bun run typecheck
bun run test

Vercel handles deployment automatically.

---

Troubleshooting

Stuck GitHub Actions workflow

gh run cancel <run-id>

# Delete and recreate tag
git push origin :refs/tags/vX.Y.Z
git tag -d vX.Y.Z
git tag -a vX.Y.Z -m "Release"
git push origin vX.Y.Z

Rollback

# Delete tag
git tag -d vX.Y.Z
git push origin :refs/tags/vX.Y.Z

# Delete release
gh release delete vX.Y.Z

# Revert if needed
git revert HEAD

macOS app not notarized

Export from Xcode Organizer ensures stapling. Verify with:

xcrun stapler validate ~/Downloads/AppName.app

---

Resources

• scripts/create-release.sh: Automated Rust release script
• Semantic Versioning
• Keep a Changelog
• Sparkle Documentation