# 1. Update CHANGELOG.md with release notes for this version
# 2. Commit and push
git add CHANGELOG.md
git commit -m "docs: add release notes for v1.2.0"
git push origin main

# 3. Tag and push — this triggers release.yml automatically
git tag v1.2.0 && git push origin v1.2.0

# Beta / pre-release (automatically flagged on GitHub)
git tag v1.2.0-beta.1 && git push origin v1.2.0-beta.1

Option B — Manual dispatch:

Go to Actions → Release → Run workflow
Enter version (e.g. 1.2.0 or 1.2.0-beta.1)
Optionally toggle publish_appcast and debug

Supported version formats: X.Y.Z, X.Y.Z-beta, X.Y.Z-beta.N, X.Y.Z-alpha.N, X.Y.Z-rc.N

Secrets Required

Secret	Required For	See
`APPLE_CERTIFICATE_P12`	Code signing	secrets-setup.md
`APPLE_CERTIFICATE_PASSWORD`	Code signing	secrets-setup.md
`APP_STORE_CONNECT_API_KEY_P8`	Notarization	secrets-setup.md
`APP_STORE_CONNECT_KEY_ID`	Notarization	secrets-setup.md
`APP_STORE_CONNECT_ISSUER_ID`	Notarization	secrets-setup.md
`SPARKLE_EDDSA_PRIVATE_KEY`	In-app auto-updates	secrets-setup.md
`CODECOV_TOKEN`	Coverage upload	secrets-setup.md
`APP_IDENTITY`	Optional signing override	secrets-setup.md

What the Release Pipeline Does

git tag v1.2.0
      │
      ▼
release.yml
  1. Extract + validate version (SemVer)
  2. Update Info.plist (CFBundleShortVersionString + CFBundleVersion = run_number)
  3. tuist install → tuist generate
  4. xcodebuild archive (arm64 + x86_64, unsigned)
  5. Import Developer ID cert into temp keychain
  6. codesign with entitlements
  7. notarytool submit + staple
  8. Create ZIP + DMG (signed), SHA256 checksums
  9. Extract release notes from CHANGELOG.md
 10. Publish GitHub Release (draft: false)
 11. Generate Sparkle appcast with EdDSA signature
 12. Deploy appcast to GitHub Pages

Debugging Failures

Enable verbose output via manual dispatch → debug: true. This prints:

P12 certificate details and contents
All identities in the signing keychain
Certificate subject and expiry dates

For detailed troubleshooting: troubleshooting.md

Beta Channel

Pre-release tags (v1.2.0-beta.1) automatically:

Set GitHub release as prerelease: true
Add <sparkle:channel>beta</sparkle:channel> to the appcast entry
Are only offered to users with Beta Updates enabled in Settings

Stable releases always win over betas of the same version (stable gets higher build number).

See release-workflow.md for the full beta channel matrix.

Workflow	Trigger	Runner	Purpose
`build.yml`	push/PR to main, develop	macos-15	Debug + release build verification
`tests.yml`	push/PR to main, develop	macos-26	Unit tests + Codecov coverage upload
`release.yml`	`v*` tag push OR manual	macos-15	Sign → notarize → DMG → GitHub release → appcast

github-actions

ClaudeBar GitHub Actions

Workflows at a Glance

Create a Release