CI-Notarized macOS Releases
CI-Notarized macOS Releases
The complete recipe for signing, notarizing, and publishing a macOS app from GitHub Actions to LicenseSeat — with every pitfall that actually happened while proving it on a real product, called out where you will hit it. Written for coding agents as much as for humans: follow it top to bottom and the first supervised run has exactly one untested surface left (Apple's own response).
Companions: Zero to Shipped is the map; Shipping Desktop Updates owns packaging and feeds. This guide owns the CI + Apple lane.
The two-workflow pattern
Never make the notarizing workflow the place you discover environment problems. Run two workflows:
1. Preflight (workflow_dispatch only, no secrets, no Apple):
same runner image, same toolchain steps, full test suite, then a
release-profile universal build with the real repo variables so the
release guards compile against the values that will actually ship, then a
lipo check. Upload the unsigned bundle as a short-lived artifact.
2. Release (triggered by publishing a GitHub Release, or manual dispatch): everything below.
A real preflight sequence caught, in five runs costing cents: a toolchain profile gap, hidden test races that only lose on loaded runners, an undocumented cross-compiler dependency, and a malformed signing-key variable that would have failed the supervised run at compile time. The supervised run then passed end to end on its first real attempt. That is the pattern working exactly as intended.
Secrets and variables — and how each one actually fails
| Name | Kind | The trap that actually happened |
|---|---|---|
APPLE_CERTIFICATE_P12 |
secret | Export must contain exactly one Developer ID Application identity — assert the count in CI |
APPLE_CERTIFICATE_PASSWORD |
secret | Wrong password only surfaces at keychain import — which is why import runs minutes before Apple contact |
APPLE_ID / APPLE_TEAM_ID |
secret | Team must be the entity shipping THIS product |
APPLE_APP_SPECIFIC_PASSWORD |
secret | Your tooling probably expects APPLE_PASSWORD — map it explicitly in the step env |
| Updater private key | secret | If the key is passwordless, leave the password secret unset — GitHub resolves an absent secret to the empty string, which is the correct value; setting it to anything else breaks signing |
| Updater PUBLIC key | variable | ⚠️ tauri signer generate writes the .pub file already base64-encoded. Storing base64(.pub-file) double-encodes it and every validator downstream rejects it. Paste the file content as-is |
| Licensing signing public key | variable | ⚠️ Base64 padding (=) survives no clipboard. A 43-char Ed25519 key is a truncated 44-char one |
sk_ releases:write token |
secret | Scope to releases only; it can publish feeds |
The one verification that counts: compile with the values. Presence in the secrets list proves nothing — three of the traps above were "set and verified" variables that had never been consumed. The preflight exists to consume them.
Validate shape before Apple. Put cheap format checks (base64 round-trip, key length, key-line structure) at the top of the release script. A malformed variable should cost 60 milliseconds and a clear error, not a build followed by a confusing signing failure.
The release workflow, step by step
on:
release:
types: [published] # publishing a Release IS the ship decision
workflow_dispatch:
inputs:
dry_run:
description: "Build, sign, NOTARIZE WITH APPLE, verify, stage — but touch no Release and publish no feed"
type: boolean
default: true
permissions:
contents: write # Release asset upload; nothing else
concurrency:
group: macos-release
cancel-in-progress: false # queue, never cancel: a cancelled feed publish
# can interleave with the next one
Label the dry run honestly. A dry run that signs and notarizes REALLY submits to Apple — it consumes a submission and involves your certificate. "Dry" must mean precisely: no Release assets, no feed publish. Say so in the input description, where the operator's finger hovers, not only in a runbook. Keep the first notarizing run human-supervised.
Import the certificate into a throwaway keychain you create per-run and
delete in an always() step, so a cancelled run cannot leave credentials
on a shared runner:
security create-keychain -p "$KEYCHAIN_PASSWORD" "$KEYCHAIN_PATH"
security set-keychain-settings -lut 21600 "$KEYCHAIN_PATH"
security unlock-keychain -p "$KEYCHAIN_PASSWORD" "$KEYCHAIN_PATH"
security import "$CERT_PATH" -P "$APPLE_CERTIFICATE_PASSWORD" -f pkcs12 \
-k "$KEYCHAIN_PATH" -T /usr/bin/codesign -T /usr/bin/security
security set-key-partition-list -S "apple-tool:,apple:,codesign:" \
-s -k "$KEYCHAIN_PASSWORD" "$KEYCHAIN_PATH" > /dev/null
Gate the identity, not just its count. Assert exactly one Developer ID Application identity arrived, then assert it is the expected one, byte-for-byte, and fail otherwise — before anything is signed:
case "$IDENTITY" in
"Developer ID Application: Your Company, LLC (TEAMID1234)") ;;
*) echo "::error::Unexpected signing identity '$IDENTITY'"; exit 1 ;;
esac
If the certificate secret is ever re-exported from the wrong keychain entry, the run dies in minute two with a clear message instead of submitting under an unintended identity. Everything Apple ever sees is signed by this name; which name is not a detail.
Check the tag matches the source version (all version files bumped together) before building, so a stale tag cannot publish a mislabeled feed.
Then build → sign → notarize → staple — and verify like you don't trust yourself:
xcrun stapler validateon the bundlespctl --assess --type execute— the actual Gatekeeper answer- verify the updater signature with an independent tool, not the one that produced it
- assert the built binary embeds the exact public config bytes you intended (the compile-time values, not what a config file claims)
lipo -infofor every architecture you promised
The Swift/Xcode flavor
Everything above is toolchain-agnostic; this section is the Xcode-specific shape of it, proven on a production Swift + Sparkle app. The client-side half — SDK pinning, key injection, sandbox entitlements, headless tests — lives in [[guides/swift-macos-integration|Integrating LicenseSeat in a Swift macOS App]].
Secrets and variables
The same five Apple values and the product's sk_ releases:write token, plus
one more:
| Name | Kind | Why |
|---|---|---|
<PRODUCT>_LICENSESEAT_API_KEY |
variable | The publishable pk_ key, injected into Info.plist at archive time. A variable, not a secret: it ships inside every binary, so it is not confidential — and leaving it unmasked is what lets the verification step print the mismatch instead of ***. Name it per product; a repo that ships more than one app will need more than one |
<PRODUCT>_LICENSESEAT_SK |
secret | The sk_ token. Swapping this with the pk_ above leaks a secret into a shipped binary and fails the publish with a 401 |
No Sparkle private key belongs in CI. When the platform holds the signing
key and signs artifacts server-side at finalize, the workflow's only release
credential is the sk_. If you are migrating off a script that ran
generate_appcast and signed on a laptop, deleting the key from the pipeline
is part of the migration, not a follow-up.
Version cross-check: the project is the source of truth
MARKETING_VERSION and CURRENT_PROJECT_VERSION are project-level build
settings, so read them from the project and check the tag against them —
never the other way round:
BUILD_SETTINGS="$(xcodebuild -project MyApp.xcodeproj -scheme MyApp \
-configuration Release -destination 'generic/platform=macOS' \
-onlyUsePackageVersionsFromResolvedFile -skipPackageUpdates \
-disablePackageRepositoryCache -showBuildSettings 2>/dev/null)"
setting() { printf '%s\n' "$BUILD_SETTINGS" | sed -n "s/^[[:space:]]*$1 = //p" | sed -n '1p'; }
VERSION="$(setting MARKETING_VERSION)"
BUILD_NUMBER="$(setting CURRENT_PROJECT_VERSION)"
[ "$RELEASE_TAG" = "v$VERSION" ] || { echo "::error::tag/version mismatch"; exit 1; }
Three non-obvious guards belong in that same step:
- Assert
PRODUCT_BUNDLE_IDENTIFIER.-showBuildSettingsprints one block per target in the scheme and this reads the first. Asserting the bundle ID proves you read the app target and not the test target — whoseMARKETING_VERSIONis whatever nobody has maintained. - Assert
ENABLE_HARDENED_RUNTIME = YES. A Developer ID build without it cannot be notarized, and finding that out from Apple wastes a submission. - Assert the lockfile did not move.
-showBuildSettingscan perform implicit package resolution; pass the pin/isolation flags shown above andgit diff --quiet -- '*Package.resolved'afterwards.
CURRENT_PROJECT_VERSION is what Sparkle compares against the installed
CFBundleVersion — it is the --bundle-version of the publish step, and
forgetting to bump it means no client ever sees the update no matter what the
marketing version says
(why).
Archive and export
Manual signing, always: CI has no Apple ID session, so automatic signing tries to reach the developer portal and fails.
xcodebuild archive \
-project MyApp.xcodeproj -scheme MyApp -configuration Release \
-destination 'generic/platform=macOS' \
-archivePath "$WORK_DIR/MyApp.xcarchive" \
-derivedDataPath "$DERIVED_DATA" \
-clonedSourcePackagesDirPath "$SOURCE_PACKAGES" \
-onlyUsePackageVersionsFromResolvedFile -skipPackageUpdates \
-disablePackageRepositoryCache \
-xcconfig "$SECRET_XCCONFIG" \
ARCHS='arm64 x86_64' ONLY_ACTIVE_ARCH=NO \
ENABLE_HARDENED_RUNTIME=YES \
CODE_SIGN_STYLE=Manual \
CODE_SIGN_IDENTITY="$SIGNING_IDENTITY" \
OTHER_CODE_SIGN_FLAGS='--timestamp'
The export options plist is method: developer-id, signingStyle: manual,
the explicit signingCertificate and teamID, and
manageAppVersionAndBuildNumber: false. Do not let exportArchive
notarize. The dual-submission flow below is what actually gets stapled, and
an export-time notarization is a third submission that buys nothing.
The identity hard-gate is identical to the one above — throwaway keychain,
count assertion, then a byte-for-byte case match on the identity string,
before anything is signed. Nothing about Xcode changes that, and the reason it
exists (a bundle ID signed by the wrong team can never be moved back) is
sharper for a project whose bundle IDs are decades old.
Verify the export before Apple sees it: plutil -extract for
CFBundleIdentifier, CFBundleShortVersionString, CFBundleVersion and your
injected publishable key; lipo -archs for every architecture you promised;
the presence of Sparkle.framework under Contents/Frameworks if the channel
ships it; and codesign -d --verbose=2 … | grep 'flags=.*runtime' — because
hardened runtime being on in the build settings and on in the signature are
different claims.
Dual notarization: the house pattern for DMG-shipped apps
If you ship a DMG, notarize and staple twice:
build → sign → zip the .app → notarize + staple the .app
→ package the DMG (containing the stapled .app)
→ sign the DMG → notarize + staple the DMG
notarytool takes archives, not bundles, so the app goes up as a ditto -c -k --sequesterRsrc --keepParent zip; the ticket is then stapled into the
.app, and that stapled app is what goes into the image.
Why both:
- Staple only the DMG and the app the customer drags to
/Applicationshas no ticket of its own — it phones home to Apple on first launch, and fails closed for a user who is offline or behind a filtered network. - Staple only the app and the DMG itself cannot be verified offline.
So verify both, with the assessment each one actually gets:
xcrun stapler validate -v "$APP"
spctl --assess --type execute --verbose=2 "$APP"
xcrun stapler validate -v "$DMG"
spctl --assess --type open --context context:primary-signature --verbose=2 "$DMG"
Two details that only surface later: codesign --force --timestamp --sign …
on the DMG is not optional — a DMG signed without a secure timestamp
notarizes fine and fails Gatekeeper once the certificate expires — and
xcrun notarytool log <submission-id> is worth fetching on every submission,
accepted or not, because it is the only place Apple explains itself.
Ordering, and recovery without a rebuild
Attach the DMG to the GitHub Release before publishing the LicenseSeat feed. If the publish step fails, the notarized artifact is already preserved and the run can be repaired with a recovery dispatch that re-publishes the existing tag. Rebuilding to fix a publish failure burns two more notarization submissions and produces a different binary than the one you already notarized — which is exactly the kind of quiet divergence that makes a support report unreproducible.
Timing and expectations
- A team's first notarization (or first in a long while) can take minutes to hours while Apple runs extra checks — that is a queue, not a judgment. A well-formed submission from an established team typically clears in ~5–15 minutes.
- A rejected notarization is routine and non-punitive: fetch the log
(
xcrun notarytool log <submission-id>), fix, resubmit deliberately. Do not machine-gun resubmissions. - Keep notarization volume boring: iterate on the preflight, not on Apple. See the team and bundle-ID hygiene section for the account-level rules — bundle IDs live and die with one team, and the cost of casual behavior there is the account.
Edge cases that bite
get-task-allow: a debug entitlement that hardened-runtime notarization rejects. Release builds must not carry it (default tooling is fine; custom entitlements files are where it sneaks in).- Zero custom entitlements is often correct. Synthetic-event posting (paste simulation) is a user-granted TCC permission, not an entitlement; on-device OCR needs nothing; WKWebView needs no JIT entitlement. Only add an entitlements file for a capability that provably requires one — and treat its addition as a security-surface change.
LSUIElementfor menubar apps belongs in the plist, not only as a runtime activation policy — declare what the app is.LSMinimumSystemVersionmust match your marketing. The plist is what macOS enforces with a clean "requires macOS X" dialog; if your website says 12+ and your plist says 10.15, unsupported users get a broken launch instead of a refusal — and your EULA's "stated requirements" language stops meaning anything.- Legal-entity names in bundle metadata: the signing certificate already carries your legal identity; volunteering additional entity names in plist fields buys nothing. Brand-only metadata is cleaner on every axis.
- The updater artifact must be packaged xattr-clean (packaging section) — notarization will happily accept an archive the updater cannot unpack.
Rehearse the update path without Apple
Before the first real release, prove publish → feed → download →
signature-verify → install → relaunch against production without touching
your stable channel or your real keys: local unnotarized builds with a
throwaway updater keypair, feed pointed at ?channel=beta, publish
with a short-lived sk_ token, watch the old build update itself. Then
yank the beta release, revoke the token, delete the throwaway keys. After
this rehearsal plus a green preflight, the supervised notarizing run has
exactly one untested surface: Apple.