electron-release

Original：🇺🇸 English
Translated

Guides Electron app release process including build, code signing, notarization, and GitHub Release with auto-update support. Use when releasing Electron apps, creating DMG installers, setting up auto-update, or troubleshooting notarization issues.

1installs
Sourcelaststance/skills
Added on

NPX Install

npx skill4agent add laststance/skills electron-release

Tags

Translated version includes tags in frontmatter
electron-releaseauto-updategithub-releasenotarizationelectron-builder

SKILL.md Content

View Translation Comparison →

Electron Release Guide

Complete release workflow for Electron applications with auto-update support.

Supported Configurations

StackPlatformBuild TypeStatus
Vite + electron-buildermacOSLocal✅ Documented
Other configurations--📝 To be added

Quick Start (macOS + Vite + electron-builder)

bash
# 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 VarPurpose
    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

FilePurposeMissing =
latest-mac.yml
Version + SHA512 hashes"No updates available"
*-arm64-mac.zip
ARM64 update payloadDownload fails on M1/M2/M3
*-mac.zip
x64 update payloadDownload fails on Intel
*.dmg
Manual downloadNo manual install option

Common Mistakes

MistakeSymptomFix
DMG only, no ZIPAuto-update silently failsUpload all ZIP files
Missing 
latest-mac.yml
"No updates available"Upload 
latest-mac.yml
Wrong ZIP filenameDownload errorRename to match 
latest-mac.yml
URLs
No notarization env varGatekeeper blocks appSet 
APPLE_KEYCHAIN_PROFILE
Spaces in filename404 on downloadRename: spaces → hyphens

Troubleshooting

"Download error" on auto-update

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

bash
# Verify latest-mac.yml is uploaded
gh release view vX.Y.Z --json assets --jq '.assets[].name' | grep yml

Gatekeeper blocks app

bash
# Rebuild with notarization
APPLE_KEYCHAIN_PROFILE=your-profile pnpm build:mac
# Check build log for "notarization successful"

electron-builder.yml Reference

yaml
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