Notarization
How Scripts/notarize.sh submits the application and the disk image to Apple's notary service, staples the
ticket and reports the result, and how to verify it independently.
This document describes a procedure. It does not state that any build has been notarized. The script itself
prints the word "notarized" only after Apple's service answered Accepted.
Credentials
- The script uses an existing
notarytoolkeychain profile. The profile name is taken from the environment variableNOTARY_PROFILEand defaults toMacLustr-Notarize. - The profile is created once, outside this repository, with
xcrun notarytool store-credentials <name>. It lives in the login keychain of the build machine. - The script never creates, prints or changes credentials. No credential is stored in the repository: no
Apple ID, app-specific password, API key or key file.
Scripts/check.shfails onAuthKey_*,.p8and similar files and on credential-like strings.
NOTARY_PROFILE=MyProfile Scripts/notarize.sh # another profile
Scripts/notarize.sh # default profile, default targetUsage
Scripts/notarize.sh [target] [name]| Argument | Default | Meaning |
|---|---|---|
target |
dist/ORIX Clean.app |
What to notarize: the application bundle or the disk image |
name |
app |
Label for the files written to build/notary/ |
The release needs two submissions:
Scripts/notarize.sh # the application
Scripts/package.sh # builds the DMG and the ZIP from the stapled app
Scripts/notarize.sh dist/ORIXClean-<version>.dmg dmg # the disk imageThe application is notarized first because package.sh refuses to run until the application is stapled, so
that the copy inside the disk image and the ZIP already carries its ticket.
What the script does
sequenceDiagram
participant S as notarize.sh
participant N as Apple notary service
participant T as stapler
S->>S: check that the target exists
S->>S: if the target is a bundle, zip it with ditto into build/notary
S->>N: notarytool submit with keychain profile, wait, JSON output
N-->>S: submission id and status
S->>N: notarytool log for the submission id
N-->>S: log saved as JSON
alt status is Accepted
S->>T: stapler staple the target
S->>T: stapler validate the target
S->>S: print RESULT notarized and stapled
else any other status
S->>S: print RESULT NOT notarized, exit 3
end
- Stops with exit code 1 if the target does not exist.
- A bundle cannot be uploaded as a directory: it is archived to
build/notary/<name>.zipwithditto -c -k --keepParent. A disk image is submitted as is. - Runs
xcrun notarytool submit … --keychain-profile "$PROFILE" --wait --output-format json. The JSON answer goes tobuild/notary/<name>.json, standard error tobuild/notary/<name>.json.err. If the command itself fails (network, credentials, malformed upload), the first lines of the error are shown and the script exits with code 2. - Reads
statusandidfrom the JSON and printssubmission <id>: <status>. - Downloads the notary log to
build/notary/<name>-log.json(best effort). - If the status is not exactly
Accepted, printsRESULT: NOT notarizedwith the log path and exits with code 3. - Staples the ticket to the original target (the bundle, not the temporary zip) with
xcrun stapler staple, then runsxcrun stapler validate. - Prints
RESULT: <target> is notarized by Apple (submission <id>) and stapled.
| Exit code | Meaning |
|---|---|
| 0 | Accepted, stapled and validated |
| 1 | Target not found |
| 2 | notarytool submit failed before a verdict |
| 3 | A verdict other than Accepted |
| other | stapler failed (the script runs with set -e) |
Files written
| File | Content |
|---|---|
build/notary/app.zip |
Upload archive of the application |
build/notary/app.json, dmg.json |
Answer of notarytool submit: id, status, message |
build/notary/app.json.err, dmg.json.err |
Standard error of the submission |
build/notary/app-log.json, dmg-log.json |
Notary log: issues found, per file |
build/ is ignored by git. Scripts/finalize.sh later reads the submission ids from app.json and
dmg.json.
Verifying independently
Do not rely on the script's last line alone; check the artifacts.
| Check | Command | Expected |
|---|---|---|
| Ticket is attached to the app | xcrun stapler validate "dist/ORIX Clean.app" |
The validate action worked! |
| Ticket is attached to the image | xcrun stapler validate dist/ORIXClean-<version>.dmg |
The validate action worked! |
| Gatekeeper accepts the app | spctl --assess --type execute --verbose=2 "dist/ORIX Clean.app" |
accepted, source=Notarized Developer ID |
| Gatekeeper accepts the image | spctl --assess --type open --context context:primary-signature --verbose=2 dist/ORIXClean-<version>.dmg |
accepted, source=Notarized Developer ID |
| Service-side record | xcrun notarytool info <submission id> --keychain-profile "$NOTARY_PROFILE" |
status: Accepted |
| Service-side history | xcrun notarytool history --keychain-profile "$NOTARY_PROFILE" |
The submission is listed |
The exact wording of spctl and stapler output can vary between macOS versions; the verdict (accepted,
validation succeeded) is what matters. The strongest end-to-end check is on a second Mac that has never seen
the build: download the image, open it, drag the application to Applications and launch it. Gatekeeper should
show the standard first-launch dialog for an application downloaded from the internet, with no warning about
an unidentified developer.
When the verdict is not Accepted
Open build/notary/<name>-log.json. Typical findings and their source in this project:
| Finding in the log | Usual cause |
|---|---|
| The signature does not include a secure timestamp | --timestamp missing from OTHER_CODE_SIGN_FLAGS |
| The executable does not have the hardened runtime enabled | ENABLE_HARDENED_RUNTIME off |
The executable requests the get-task-allow entitlement |
A Debug build, or base entitlements injected |
| The binary is not signed with a valid Developer ID certificate | Ad hoc or development identity used |
Scripts/sign.sh checks the last three before any upload. Fix the cause, run Scripts/sign.sh again and
resubmit; a rejected submission cannot be amended.
Notes
- Notarization requires network access from the build machine. The application itself contains no network code; this is a property of the release tooling only.
- Stapling lets Gatekeeper verify the ticket offline. An unstapled but notarized application still passes when the Mac is online, but the release process requires stapling.
- The ZIP artifact is not submitted separately: it is created from the already stapled application bundle.