jaspermayone.com
Simple App to help @jaspermayone make it through COMP1050 with a professor who won't use version control.
1# Release Process
2
3This document describes how to release ZipMerge.
4
5## Local Release Script (Recommended)
6
7The easiest way to create a release is using the local `release.sh` script.
8
9**Option 1: Create tag first (recommended for custom tag messages)**
10```bash
11# Create a tag with a custom message
12git tag -a v1.0.0 -m "Version 1.0.0 - Your custom message"
13
14# Run the release script (will use existing tag)
15./release.sh v1.0.0
16```
17
18**Option 2: Let the script create the tag**
19```bash
20# Script will create a simple tag automatically
21./release.sh v1.0.0
22```
23
24This script will:
251. Build the app with Developer ID signing
262. Notarize the app with Apple
273. Use existing git tag or create one if needed
284. Push the tag to GitHub
295. Create a GitHub release with the signed .zip
306. Calculate the SHA256 hash
317. Automatically update the Homebrew cask
328. Commit and push the cask update
33
34**Prerequisites:**
35- `gh` CLI installed (`brew install gh`) and authenticated
36- Developer ID Application certificate in Keychain
37- Apple ID app-specific password (create at https://appleid.apple.com/account/manage)
38
39The script will prompt for your Apple ID and app-specific password.
40
41## Alternative: GitHub Actions (Optional)
42
43If you prefer CI/CD, there's also a GitHub Actions workflow. However, it requires exporting your signing certificate.
44
45## Required GitHub Secrets (GitHub Actions only)
46
47Before creating your first release, set up these secrets in GitHub repository settings (Settings → Secrets and variables → Actions):
48
49### 1. CERTIFICATE_BASE64
50
51Your Developer ID Application certificate exported as base64.
52
53**How to create:**
54
55```bash
56# Export your Developer ID certificate from Keychain Access
57# 1. Open Keychain Access
58# 2. Find "Developer ID Application: <Your Name> (M67B42LX8D)"
59# 3. Right-click → Export "Developer ID Application..."
60# 4. Save as certificate.p12 with a password
61
62# Convert to base64
63base64 -i certificate.p12 | pbcopy
64
65# Paste the output as CERTIFICATE_BASE64 secret in GitHub
66# Then delete the certificate.p12 file
67rm certificate.p12
68```
69
70### 2. CERTIFICATE_PASSWORD
71
72The password you used when exporting the certificate.p12 file.
73
74### 3. APPLE_ID
75
76Your Apple ID email address (the one associated with your developer account).
77
78### 4. APPLE_ID_PASSWORD
79
80An app-specific password for notarization (NOT your Apple ID password).
81
82**How to create:**
83
841. Go to https://appleid.apple.com/account/manage
852. Sign in with your Apple ID
863. In the Security section, under "App-Specific Passwords", click "Generate Password"
874. Enter "GitHub Actions Notarization" as the name
885. Copy the generated password and save it as APPLE_ID_PASSWORD in GitHub
89
90## Manual GitHub Actions Release (Alternative)
91
92If you prefer to use GitHub Actions instead of the local script:
93
94```bash
95# Ensure you're on main branch with latest changes
96git checkout main
97git pull
98
99# Create and push a version tag
100git tag v1.0.0
101git push origin v1.0.0
102```
103
104The GitHub Actions workflow will automatically build, sign, notarize, and create a release. However, you'll need to manually update the Homebrew cask afterward (the local script does this automatically).
105
106## Troubleshooting
107
108### Notarization fails
109
110- Verify APPLE_ID and APPLE_ID_PASSWORD are correct
111- Ensure app-specific password hasn't expired
112- Check notarization logs in the GitHub Actions output
113
114### Code signing fails
115
116- Verify CERTIFICATE_BASE64 is correctly encoded
117- Ensure CERTIFICATE_PASSWORD matches the export password
118- Certificate must be "Developer ID Application" (not "Apple Development")
119
120### Build fails
121
122- Check that Xcode version on GitHub Actions supports your Swift version
123- Verify project builds locally first with `xcodebuild`