​
VibeTunnel Release Guide - Quick Reference

This guide provides a streamlined release process based on lessons learned from beta.13.

​
🚀 Quick Release Commands

# 1. Pre-release health check
./scripts/release-health-check.sh

# 2. Set environment variables
export SPARKLE_ACCOUNT="VibeTunnel"
export CI=false
export SKIP_NODE_CHECK=false

# 3. Run the release
./scripts/release.sh beta 14  # For next beta

# 4. Monitor progress in another terminal
./scripts/release-progress.sh

# 5. If interrupted, resume
./scripts/release.sh --resume

​
📋 Pre-Release Checklist

Before starting any release:

​
1. Version Numbers

  • Update mac/VibeTunnel/version.xcconfig:
    • MARKETING_VERSION = 1.0.0-beta.14
    • CURRENT_PROJECT_VERSION = 203 (increment from last)
  • Update web/package.json to match
  • Update web/package.npm.json to match
  • Update CHANGELOG.md with release notes

​
2. Environment Setup

# Required environment variables
export SPARKLE_ACCOUNT="VibeTunnel"
export CI=false
export SKIP_NODE_CHECK=false

# Notarization credentials (if not already set)
export APP_STORE_CONNECT_KEY_ID="your_key_id"
export APP_STORE_CONNECT_ISSUER_ID="your_issuer_id"
export APP_STORE_CONNECT_API_KEY_P8="-----BEGIN PRIVATE KEY-----
your_private_key_content
-----END PRIVATE KEY-----"

​
3. Clean State

# Ensure clean git state
git status  # Should be clean
git pull --rebase origin main

# Run health check
./scripts/release-health-check.sh

​
🔧 Troubleshooting

​
Node.js Detection Issues

If the build fails with “Node.js is required”: 
# Test Node.js detection
./scripts/check-node-simple.sh

# If using nvm, ensure it's loaded
source ~/.nvm/nvm.sh
nvm use 20  # or your version

# Create symlinks if needed (requires sudo)
sudo ln -s $(which node) /usr/local/bin/node
sudo ln -s $(which pnpm) /usr/local/bin/pnpm

​
Release Script Timeouts

The release process can take 20-30 minutes:
  • Build: 2-5 minutes
  • Notarization: 5-15 minutes
  • DMG creation: 1-2 minutes
If it times out: 
# Check current status
./scripts/release-progress.sh

# Resume from last step
./scripts/release.sh --resume

​
Manual Recovery

If the release script fails after notarization: 
# 1. Create GitHub release manually
./scripts/generate-release-notes.sh 1.0.0-beta.14 > notes.md
gh release create "v1.0.0-beta.14" \
  --title "VibeTunnel 1.0.0-beta.14" \
  --notes-file notes.md \
  --prerelease \
  build/VibeTunnel-*.dmg \
  build/VibeTunnel-*.zip

# 2. Sign DMG for Sparkle
sign_update -f private/sparkle_ed_private_key \
  build/VibeTunnel-1.0.0-beta.14.dmg \
  --account VibeTunnel

# 3. Update appcast manually
# Add the signature to appcast-prerelease.xml
# Then commit and push
git add ../appcast-prerelease.xml
git commit -m "Update appcast for v1.0.0-beta.14"
git push

​
📊 New Tools

​
Release Progress Monitor

Shows real-time release progress with visual indicators: 
./scripts/release-progress.sh
Features:
  • Step-by-step progress tracking
  • Duration for each step
  • Idle time warnings
  • Artifact status

​
Release Health Check

Comprehensive pre-release validation: 
./scripts/release-health-check.sh
Checks:
  • Git status and branch
  • Environment variables
  • Build tools availability
  • Code signing certificates
  • Version synchronization
  • Disk space
  • Appcast validity

​
Simplified Node.js Check

More robust Node.js detection: 
./scripts/check-node-simple.sh

​
🎯 Best Practices

  1. Always run health check first - Catches issues before they cause failures
  2. Use progress monitor - Keep track of long-running operations
  3. Set all environment variables - Prevents mid-release failures
  4. Keep versions synchronized - Update all version files before starting
  5. Document in CHANGELOG.md - Required for release notes generation
  6. Don’t run in background - Use screen/tmux if needed, but keep foreground

​
📝 Version Management

​
Version Files to Update

  1. mac/VibeTunnel/version.xcconfig - Source of truth
  2. web/package.json - Must match macOS version
  3. web/package.npm.json - For npm package release
  4. CHANGELOG.md - Release notes

​
Build Number Rules

  • Must increment for EVERY release
  • Must be unique across all releases
  • Sparkle uses build numbers, not version strings
  • Check existing: grep '<sparkle:version>' ../appcast*.xml

​
🚨 Common Issues

​
”Uncommitted changes detected”

  • Commit all changes before releasing
  • Or stash temporarily: git stash

​
”Build number already exists”

  • Increment CURRENT_PROJECT_VERSION in version.xcconfig
  • Must be higher than all previous releases

​
”Version mismatch”

  • Ensure web/package.json matches mac version
  • Run health check to verify

​
DMG stuck volumes

# List stuck volumes
ls /Volumes/VibeTunnel*

# Force unmount
for vol in /Volumes/VibeTunnel*; do
  hdiutil detach "$vol" -force
done

​
📚 Summary

The improved release process provides:
  • Better error handling with environment variable defaults
  • Visual progress tracking
  • Comprehensive pre-flight validation
  • Clear recovery procedures
  • Simplified troubleshooting
For the smoothest release experience:
  1. Run health check
  2. Set environment variables
  3. Use the standard release script
  4. Monitor with progress tool
  5. Resume if interrupted
The release should complete in 20-30 minutes with clear visibility into each step.