Electron Release Guide
Complete release workflow for Electron applications with auto-update support.
Supported Configurations
| Stack | Platform | Build Type | Status |
|---|
| Vite + electron-builder | macOS | Local | ✅ Documented |
| Other configurations | - | - | 📝 To be added |
Quick Start (macOS + Vite + electron-builder)
# 1. Build with notarization
APPLE_KEYCHAIN_PROFILE=your-profile pnpm build:mac
# 2. Rename ZIPs (GitHub converts spaces to dots)
cp "dist/App Name-X.Y.Z-arm64-mac.zip" "dist/App-Name-X.Y.Z-arm64-mac.zip"
cp "dist/App Name-X.Y.Z-mac.zip" "dist/App-Name-X.Y.Z-mac.zip"
# 3. Create release with ALL files
gh release create vX.Y.Z \
dist/latest-mac.yml \
"dist/App-Name-X.Y.Z-arm64-mac.zip" \
"dist/App-Name-X.Y.Z-mac.zip" \
dist/app-name-X.Y.Z-arm64.dmg \
dist/app-name-X.Y.Z-x64.dmg \
--title "vX.Y.Z" --notes "Release notes..."
Complete Workflow
Phase 1: Pre-Release
- Update version in
package.json - Commit version bump:
git add package.json git commit -m "chore(release): bump version to X.Y.Z" git push origin main
Phase 2: Build
- Build with notarization:
APPLE_KEYCHAIN_PROFILE=your-profile pnpm build:mac Env Var Purpose APPLE_KEYCHAIN_PROFILE Keychain profile for notarization Alternative: APPLE_ID, APPLE_APP_SPECIFIC_PASSWORD, APPLE_TEAM_ID Direct credentials - Verify build output:
ls -la dist/*.dmg dist/*.zip dist/*.yml Expected files:
- latest-mac.yml - Auto-update metadata - App Name-X.Y.Z-arm64-mac.zip - ARM64 update payload - App Name-X.Y.Z-mac.zip - x64 update payload - app-name-X.Y.Z-arm64.dmg - ARM64 installer - app-name-X.Y.Z-x64.dmg - x64 installer
Phase 3: Prepare Release Assets
- Rename ZIP files (critical for auto-update):
# GitHub converts spaces to dots, but latest-mac.yml expects hyphens cp "dist/App Name-X.Y.Z-arm64-mac.zip" "dist/App-Name-X.Y.Z-arm64-mac.zip" cp "dist/App Name-X.Y.Z-mac.zip" "dist/App-Name-X.Y.Z-mac.zip" - Verify
latest-mac.yml URLs match renamed files: cat dist/latest-mac.yml # Check that 'url:' entries match your renamed ZIP filenames
Phase 4: GitHub Release
- Create release with all required files:
gh release create vX.Y.Z \ dist/latest-mac.yml \ "dist/App-Name-X.Y.Z-arm64-mac.zip" \ "dist/App-Name-X.Y.Z-mac.zip" \ dist/app-name-X.Y.Z-arm64.dmg \ dist/app-name-X.Y.Z-x64.dmg \ --title "vX.Y.Z" \ --notes "$(cat <<'EOF' ## What's Changed - Feature 1 - Bug fix 2 EOF)" - Verify release assets:
gh release view vX.Y.Z --json assets --jq '.assets[].name'
Required Files for Auto-Update
| File | Purpose | Missing = |
|---|
latest-mac.yml | Version + SHA512 hashes | "No updates available" |
*-arm64-mac.zip | ARM64 update payload | Download fails on M1/M2/M3 |
*-mac.zip | x64 update payload | Download fails on Intel |
*.dmg | Manual download | No manual install option |
Common Mistakes
| Mistake | Symptom | Fix |
|---|
| DMG only, no ZIP | Auto-update silently fails | Upload all ZIP files |
Missing latest-mac.yml | "No updates available" | Upload latest-mac.yml |
| Wrong ZIP filename | Download error | Rename to match latest-mac.yml URLs |
| No notarization env var | Gatekeeper blocks app | Set APPLE_KEYCHAIN_PROFILE |
| Spaces in filename | 404 on download | Rename: spaces → hyphens |
Troubleshooting
"Download error" on auto-update
# Check if filenames match
cat dist/latest-mac.yml | grep url:
gh release view vX.Y.Z --json assets --jq '.assets[].name'
# URLs in yml must exactly match asset names
"No updates available"
# Verify latest-mac.yml is uploaded
gh release view vX.Y.Z --json assets --jq '.assets[].name' | grep yml
Gatekeeper blocks app
# Rebuild with notarization
APPLE_KEYCHAIN_PROFILE=your-profile pnpm build:mac
# Check build log for "notarization successful"
electron-builder.yml Reference
mac:
target:
- target: dmg
arch: [arm64, x64]
- target: zip
arch: [arm64, x64]
notarize: true
hardenedRuntime: true
publish:
provider: github
owner: your-org
repo: your-repo
Success Criteria
- Build completes with "notarization successful"
- All 5 files uploaded to GitHub Release
- ZIP filenames match
latest-mac.yml URLs exactly - Test: older version detects update
- Test: download and install succeeds
