Agent-Skills.md

Agent Skills: Release Workflows

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.

UncategorizedID: thrashr888/thrashr888-agent-kit/github-releases
3

Install this agent skill to your local

pnpm dlx add-skill https://github.com/thrashr888/thrashr888-agent-kit/tree/HEAD/skills/github-releases

Skill Files

Browse the full folder contents for github-releases.

Download Skill

Loading file tree…

skills/github-releases/SKILL.md

Skill Metadata

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.

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