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