Electron Release Guide

Supported Configurations

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

1. Update version in

   package.json

2. Commit version bump:
   bash

   git add package.json
   git commit -m "chore(release): bump version to X.Y.Z"
   git push origin main

Phase 2: Build

1. Build with notarization:
   bash

   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

2. Verify build output:
   bash

   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

1. Rename ZIP files (critical for auto-update):
   bash

   # 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"

2. Verify

   latest-mac.yml

   URLs match renamed files:
   bash

   cat dist/latest-mac.yml
   # Check that 'url:' entries match your renamed ZIP filenames

Phase 4: GitHub Release

1. Create release with all required files:
   bash

   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
   )"

2. Verify release assets:
   bash

   gh release view vX.Y.Z --json assets --jq '.assets[].name'

Required Files for Auto-Update

latest-mac.yml

*-arm64-mac.zip

*-mac.zip

*.dmg

Common Mistakes

latest-mac.yml

latest-mac.yml

latest-mac.yml

APPLE_KEYCHAIN_PROFILE

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