DOCS LLMs

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 validate on the bundle
  • spctl --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 -info for 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. -showBuildSettings prints 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 — whose MARKETING_VERSION is 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. -showBuildSettings can perform implicit package resolution; pass the pin/isolation flags shown above and git 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 /Applications has 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.
  • LSUIElement for menubar apps belongs in the plist, not only as a runtime activation policy — declare what the app is.
  • LSMinimumSystemVersion must 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.