Notarization
This page describes how ORIX DJ is notarized by Apple and how the ticket is stapled, as implemented by Scripts/notarize.sh. Notarization is done twice per release: once for the application and once for the disk image. No submission has been made yet for version 1.0.0; submission identifiers and tool output will be recorded here after the release run.
Related pages: signing, distribution, release checklist.
Prerequisites
| Requirement | Detail |
|---|---|
| A signed application | dist/ORIX DJ.app, produced by Scripts/sign.sh: Developer ID signature, Hardened Runtime, secure timestamp, no get-task-allow (all checked by that script, see signing) |
| A notarytool keychain profile | The script uses an existing profile. Its name is taken from the environment variable NOTARY_PROFILE and defaults to MacLustr-Notarize. A notarytool profile exists on the build machine |
| Network access to Apple's notary service | notarytool submit --wait blocks until Apple answers |
The script never creates, prints or modifies credentials. Creating the profile (xcrun notarytool store-credentials) is a one-time manual operation that is not part of this repository, and .gitignore excludes notary*.json, *.p8, AuthKey_* and asc.env.
Usage
Scripts/notarize.sh [target] [name]| Argument | Default | Meaning |
|---|---|---|
target |
dist/ORIX DJ.app |
the bundle or file to notarize |
name |
app |
short name used for the files written under build/notary/ |
Scripts/release.sh calls it twice:
Scripts/notarize.sh "dist/ORIX DJ.app" app
Scripts/notarize.sh "dist/ORIX-DJ-$VERSION.dmg" dmgWhat the script does
It runs from the repository root with set -euo pipefail.
| Step | Action | Outcome on failure |
|---|---|---|
| 1 | Check that the target exists | exit 1: "not found. Run Scripts/sign.sh first." |
| 2 | Create build/notary/ |
|
| 3 | If the target is a directory (the .app), compress it to build/notary/<name>.zip with ditto -c -k --keepParent. A file target (the .dmg) is submitted as is |
|
| 4 | xcrun notarytool submit <file> --keychain-profile "$PROFILE" --wait --output-format json, standard output to build/notary/<name>.json, standard error to build/notary/<name>.json.err |
exit 2: "Notary service refused the submission" followed by the first 8 lines of the error file |
| 5 | Read status and id from the JSON with /usr/bin/python3 and print submission <id>: <status> |
|
| 6 | Fetch the notary log: xcrun notarytool log <id> --keychain-profile "$PROFILE" build/notary/<name>-log.json (errors ignored) |
|
| 7 | Require status to be exactly Accepted |
exit 3: "RESULT: NOT notarized. See build/notary/-log.json" |
| 8 | xcrun stapler staple <target> |
non-zero status stops the script |
| 9 | xcrun stapler validate <target> |
non-zero status stops the script |
| 10 | Print RESULT: <target> is notarized by Apple (submission <id>) and stapled. |
Two properties of this sequence matter:
- The success message is printed only after Apple answered
Acceptedand both stapler commands succeeded. Any other status (Invalid,Rejected, a timeout) ends with a non-zero exit code, which stopsScripts/release.sh. - The log is downloaded before the status is tested, so a rejected submission leaves
build/notary/<name>-log.jsonon disk with Apple's list of issues.
Why two submissions
| Submission | Submitted file | Stapled object | Purpose |
|---|---|---|---|
app |
build/notary/app.zip (a ZIP of the app made only for upload) |
dist/ORIX DJ.app |
The ticket is attached to the bundle itself, so the app passes Gatekeeper offline wherever it is copied, including when extracted from the release ZIP |
dmg |
dist/ORIX-DJ-<version>.dmg |
the disk image | The signed disk image carries its own ticket, so mounting it does not depend on an online check |
The order is fixed by the scripts: Scripts/package.sh refuses to run unless xcrun stapler validate "dist/ORIX DJ.app" succeeds, so the disk image and the ZIP always contain an already stapled application. The release ZIP (dist/ORIX-DJ-<version>.zip) is not submitted separately: a ZIP cannot be stapled, and it contains the stapled app. Scripts/finalize.sh extracts it and validates the app inside (see distribution).
Files written
| File | Content |
|---|---|
build/notary/app.zip |
upload archive of the application |
build/notary/app.json, build/notary/dmg.json |
notarytool JSON answer (id, status, ...) |
build/notary/app.json.err, build/notary/dmg.json.err |
standard error of notarytool |
build/notary/app-log.json, build/notary/dmg-log.json |
Apple's notary log for the submission |
build/ is ignored by git. Scripts/finalize.sh later reads the two JSON answers to copy the submission identifiers and statuses into dist/release.json.
Results of the release run
Nothing below has been produced yet.
Application
| Field | Value |
|---|---|
| Profile used | MacLustr-Notarize unless NOTARY_PROFILE was set |
| Submission ID | eafc4e24-d278-4460-8cef-0d7827e2481e |
| Status | Accepted ("Ready for distribution") |
Issues in build/notary/app-log.json |
none (issues: null) |
xcrun stapler staple / validate "dist/ORIX DJ.app"Processing: dist/ORIX DJ.app
The validate action worked!Disk image
| Field | Value |
|---|---|
| Submission ID | 4c301728-4b75-4c88-b3b2-831d986bcbaa (an earlier submission of a plain fallback image was superseded when the designed image was rebuilt) |
| Status | Accepted ("Ready for distribution") |
Issues in build/notary/dmg-log.json |
none (issues: null) |
xcrun stapler staple / validate "dist/ORIX-DJ-1.0.0.dmg"Processing: dist/ORIX-DJ-1.0.0.dmg
The validate action worked!Checking a notarized artifact by hand
xcrun stapler validate "dist/ORIX DJ.app"
xcrun stapler validate dist/ORIX-DJ-1.0.0.dmg
spctl --assess --type execute --verbose=2 "dist/ORIX DJ.app"
spctl --assess --type open --context context:primary-signature --verbose=2 dist/ORIX-DJ-1.0.0.dmg
xcrun notarytool log <submission-id> --keychain-profile MacLustr-NotarizeThese are the commands Scripts/finalize.sh runs (except the last). For a notarized Developer ID build the two spctl assessments are expected to answer accepted with source=Notarized Developer ID; the actual answers will be recorded in distribution after the run.
If a submission is refused
The script gives three distinct exit codes, which map to three situations:
| Exit code | Situation | Where to look |
|---|---|---|
| 1 | nothing to submit | run Scripts/sign.sh (or Scripts/package.sh for the disk image) first |
| 2 | notarytool itself failed: unknown profile, expired credentials, no network, agreement not accepted | build/notary/<name>.json.err (first lines are printed) |
| 3 | Apple processed the submission and did not accept it | build/notary/<name>-log.json |
The usual causes of an Invalid status are exactly what Scripts/sign.sh checks beforehand: a binary without Hardened Runtime, a signature without secure timestamp, a get-task-allow entitlement, or unsigned nested code. Since the app has no nested frameworks and no entitlements (see signing), none is expected, but this has not been confirmed by a real submission.
After fixing the cause, the application must be rebuilt and re-signed with Scripts/sign.sh (which erases dist/), and the whole sequence repeated: a stapled ticket belongs to one exact build.
What notarization does not establish
Notarization is an automated malware and signing check by Apple. It does not test the application's behaviour. That the notarized build starts on a Mac other than the build machine, plays audio, and behaves correctly under the Hardened Runtime are separate gates in the release checklist, none of which has been passed yet.