Releasing Brood (macOS)

Releasing Brood (macOS)

This repo ships via GitHub Releases.

When you push a tag like v0.1.0, GitHub Actions will:

• run a remote macOS clean-machine smoke install (build DMG, install, launch)
• build a universal macOS app bundle
• stage the native Rust engine binary at desktop/src-tauri/resources/brood-rs
• code sign it (Developer ID Application)
• notarize it
• attach the signed/notarized .dmg to a draft GitHub Release for that tag

Smoke details:

• Workflow: .github/workflows/desktop-clean-machine-smoke.yml
• Script: scripts/macos_clean_machine_smoke.sh

One-Time Setup (GitHub Repo Secrets)

Set these secrets in your GitHub repository:

• APPLE_CERTIFICATE: Base64-encoded .p12 containing your Developer ID Application certificate.
• APPLE_CERTIFICATE_PASSWORD: Password for the .p12.
• APPLE_ID: Apple ID email used for notarization.
• APPLE_PASSWORD: App-specific password (or notarization password) for APPLE_ID.
• APPLE_TEAM_ID: Your Apple Team ID (example: JU3DQ69K6R).
• BROOD_RELEASE_TOKEN (recommended): PAT used for GitHub Release create/upload calls in publish.yml.
  • Use a token with repo contents write access (repo scope for classic PAT, or equivalent fine-grained permission).
  • If omitted, workflow falls back to the default workflow token.

Notes:

• The workflow imports the certificate into a temporary build keychain and auto-detects the Developer ID Application identity to use.
• Release staging signs resources/brood-rs with hardened runtime + secure timestamp before notarization.
• The workflow enforces tag == v${tauri.conf.json package.version} to avoid accidental mismatches.

Cut A Release

1. Update versions (must match):
   • desktop/package.json version
   • desktop/src-tauri/tauri.conf.json package.version
   • desktop/src-tauri/Cargo.toml [package].version
2. Update CHANGELOG.md.
3. Commit the changes.
4. Tag and push:
   • git tag vX.Y.Z
   • git push origin vX.Y.Z
5. Wait for the publish workflow to finish.
6. Publish the draft release on GitHub (or change releaseDraft to false in the workflow once you're confident).

Optional: Disposable Remote Mac Snapshot Run

If you use a cloud Mac provider, keep one machine snapshot in a clean state and run:

git clone <repo-url>
cd brood
npm --prefix desktop ci
npm --prefix desktop run tauri build -- --bundles dmg --ci -v
scripts/macos_clean_machine_smoke.sh

Then discard/revert the snapshot. This gives repeatable install confidence without using multiple physical Macs.

Notarization Troubleshooting

If notarization fails with messages referencing Contents/Resources/resources/brood-rs (unsigned, missing timestamp, or no hardened runtime), confirm:

• APPLE_SIGNING_IDENTITY is detected in the workflow.
• scripts/stage_rust_engine_binary.sh ran during beforeBuildCommand.
• The release is built from a commit that includes the signing step for staged brood-rs.