Release and notarization runbook
Distribution is direct (Developer ID + notarization). The app is not sandboxed; it uses the Hardened Runtime and
one entitlement, com.apple.security.automation.apple-events.
Prerequisites on the build Mac
- Xcode with the macOS SDK,
xcodegen,create-dmg. - A Developer ID Application identity in the login keychain (
security find-identity -v -p codesigning). - A notarytool keychain profile. The scripts use
NOTARY_PROFILE(defaultMacLustr-Notarize) and never create, print or modify credentials. Check it answers:xcrun notarytool history --keychain-profile "$NOTARY_PROFILE".
Steps
# 1. Version: edit MARKETING_VERSION / CURRENT_PROJECT_VERSION in project.yml, update CHANGELOG.md
# 2. Everything in one command:
Scripts/release/release.shrelease.sh stops at the first failure and does, in order:
Scripts/test/test-all.sh— every package; writesdocs/release/test-report.json. (Run it underScripts/test/with-dev-keys.shbeforehand to include the live provider suites.)Scripts/check-headers.sh.Scripts/build/build.sh release— XcodeGen, Release build (arm64 + x86_64), Developer ID signing with a secure timestamp, intodist/ORIX OS Automation.app.Scripts/release/secret-scan.sh "dist/ORIX OS Automation.app"— fails on credential-shaped strings in the repository, its history or the bundle; on the development credential adapter being present in the binary; on internal host names.Scripts/release/sign.sh— verifies identity, Hardened Runtime, timestamp, bundle identifier, deep signature, and that no debug entitlement is present.Scripts/release/notarize.sh <app> app—notarytool submit --wait; onAccepted, staples. Anything else stops the release and leaves Apple's log inbuild/notary/app-log.json.Scripts/release/package.sh all— ZIP and a signed DMG.Scripts/release/notarize.sh <dmg> dmg— notarizes and staples the disk image.- Checksums,
spctlassessment of the app and the DMG. - Writes
docs/release/release-<version>-<build>.mdfrom the tools' own output (signature, architectures, entitlements, submission ids and statuses, staple validation, Gatekeeper verdicts, SHA-256).
"Notarized" is only ever printed after Apple answered Accepted.
After the build
- Open the DMG on another Mac or another user account: drag to Applications, launch, go through the welcome guide, confirm the Keychain item is created on key entry, enable and disable the background agent, quit.
- Publish the DMG, the ZIP,
SHA256SUMS.txtand the release notes together.
If notarization is rejected
Read build/notary/<name>-log.json. Usual causes: an unsigned or ad-hoc-signed nested binary, a missing secure
timestamp, the Hardened Runtime disabled on a helper, a debug entitlement (get-task-allow). Fix the cause and
run the release again; never disable the Hardened Runtime or strip the signature check to get through.
Updates
This version has no automatic updater. Sparkle 2 (EdDSA-signed appcasts, the installer running as an XPC service) is the candidate; it would be the first third-party dependency and needs its own review before it is added. Until then, updates are installed by replacing the app from a new notarized DMG.