CI/CD September 8, 2026 ~14 min macOS notarization Apple Notary API

Does macOS App Notarization Need a Mac? 2026 CI Deployment Decision

This guide separates macOS build, signing, packaging, notarization, stapling, and validation into distinct CI stages. It explains when a Linux controller is sufficient, when a real Mac is still required, and how to choose between a dedicated remote Mac, a mixed CI design, or an on-demand publishing node.

The pipeline can upload a macOS archive from Linux, but the release still fails at signing, stapling, or final validation.

Use a mixed deployment: let a general CI node orchestrate jobs and keep a real Mac for macOS builds, Developer ID signing, Apple-tool validation, and ticket stapling.

This guide is for platform engineers who run Linux-first CI and need to add macOS software delivery; macOS developers automating signing and notarization; and technical leads deciding between a permanent remote Mac and an on-demand publishing node.

The answer depends on which release stage you mean

Does macOS App Notarization Need a Mac? Not always. A Linux-based system can evaluate an Apple Notary API integration for submitting an existing artifact and retrieving its result. That does not mean Linux can reliably replace every part of the macOS release chain.

Apple separates the workflow into several responsibilities:

Build the application or create the release archive.
Sign the application and nested code with a Developer ID identity.
Package the signed product for distribution.
Submit the package to Apple for notarization.
Query the submission state and retrieve diagnostic logs.
Staple the notarization ticket when the distribution format requires it.
Validate the final file before publishing it.

Apple’s official notarization workflow distinguishes submission from the local preparation and distribution steps. The Apple notarization workflow documentation is therefore more useful for architecture decisions than the simplified statement that “notarization means uploading a file.”

The first decision is simple:

If the team already has a signed, reproducible artifact and only needs a service-side submission and status query, evaluate a Linux-compatible Apple Notary API client.
If the pipeline starts with an Xcode project, signs nested code, creates a distribution package, staples a ticket, or performs Apple command-line validation, retain a real Mac.
If both conditions apply, use a general CI controller plus a remote Mac CI worker.

The upload step is only one checkpoint. A successful submission does not prove that the file users will download is correctly signed, stapled, and accepted by the intended macOS security checks.

Stage one: produce an artifact that can be audited

The first input to notarization must be a finished distribution artifact, not an ambiguous build directory. Depending on the product, that may be an application bundle, installer package, or disk image. The important property is repeatability: the same source revision and declared build inputs should produce an artifact that another job can identify and verify.

For an Xcode project, the build and archive stage normally belongs on a Mac because it depends on the Apple development toolchain. The Apple distribution signing guidance describes the relationship between the product and its distribution signing requirements. A Linux controller can trigger this stage, but it does not become the build environment merely because it can start a job.

A useful stage contract should record:

Source revision or immutable build reference.
Build command and selected scheme.
Output artifact path.
Artifact digest generated by the CI system.
Target architecture and packaging format.
Whether the output is unsigned, signed, or ready for submission.

Do not pass a mutable directory between jobs and call it a release. Upload a named artifact to controlled storage, then have the next stage retrieve that exact object. This prevents a later signing job from accidentally processing a different build than the one reviewed by the release job.

Release boundary: Treat “build complete” and “ready for notarization” as different states. The latter should already have its intended bundle structure, embedded resources, entitlements, and nested code layout.

If the team starts with an existing signed artifact, the Mac requirement may be narrower. A Linux job can inspect metadata, calculate a digest, manage artifact storage, and potentially call the Apple service through the Apple Notary API. It should not silently assume that the artifact is suitable for stapling or final local validation. Those actions must be tested against the exact distribution format.

Stage two: isolate Developer ID signing from orchestration

Notarization does not replace Developer ID signing. The product must be signed before it is submitted, and nested executable code can introduce failures even when the outer application appears correctly signed.

The signing stage should verify at least four things:

The expected signing identity is available to the job.
Nested code is signed with the intended identity.
Entitlements and hardened runtime settings match the product design.
The signing command runs under the intended execution account.

Use placeholders for sensitive values in logs:

<TEAM_ID>
<SIGNING_IDENTITY>
<KEYCHAIN_PROFILE>
<SUBMISSION_ID>
<ARTIFACT_PATH>

Never print private key material, certificate contents, authentication profiles, or complete credential configuration in a public CI log. A successful build job is not permission to expose the signing environment to every runner.

A dedicated remote Mac offers the cleanest boundary when signing is a frequent operation. The machine can hold a restricted keychain, run the Apple command-line tools, and accept jobs only from the CI controller. A shared Mac can work, but it requires stronger workspace cleanup, account isolation, queue control, and post-job keychain checks. An external signing step may reduce direct credential exposure on the build node, but it adds an artifact transfer boundary and another failure domain.

The acceptance evidence should include:

The signing verification result for the outer application.
The result for important nested executables.
The execution account used by the job.
The keychain access state before and after the job.
The exact artifact digest before signing and after packaging.
A failed-signing test that proves the pipeline stops before submission.

A common design error is to let the Linux controller own the entire release secret set. In a mixed design, the controller should know how to request a job and collect a result. The Mac worker should be the only place where the signing operation and its protected keychain are available.

For teams building a repeatable remote Mac development environment, the same separation matters outside CI: interactive troubleshooting access should not automatically grant release credentials, and release jobs should not depend on an engineer’s personal login session.

Stage three: choose notarytool or the Apple Notary API

The choice between notarytool and the Apple Notary API is mainly an execution-boundary decision, not a claim that one path is universally faster.

Use notarytool when the submission job already runs on a Mac and the team wants a direct Apple command-line integration. A typical command pattern is:

xcrun notarytool submit <ARTIFACT_PATH> \
  --keychain-profile <KEYCHAIN_PROFILE> \
  --wait

The exact authentication setup, supported arguments, and output behavior must be checked against Apple’s current notarytool and custom workflow documentation. Keep the command versioned with the pipeline rather than copying a credential profile manually onto an unknown machine.

Use the Apple Notary API when a non-macOS controller needs to submit an existing artifact and query its result without invoking notarytool on the controller. The Apple Notary API overview and the Submit Software endpoint define the service-side model. The API route is attractive when Linux already owns workflow orchestration, retry logic, artifact storage, and release approvals.

The two paths have different operational responsibilities:

notarytool keeps command execution close to the Mac toolchain and is straightforward when the worker already has the required Apple environment.
The API separates submission from the Mac, but the controller must implement authentication, request retries, state polling, log retrieval, and failure classification.
notarytool can fit a Mac-native script with a clear exit status.
The API can fit a platform-wide release service that already handles HTTP clients and structured job state.
Neither path proves that the final distributed file has been stapled or locally validated.

The API should not be treated as a shortcut around signing. It receives a candidate artifact for Apple’s service-side checks. The signing and packaging decisions were made earlier, and the final release job remains responsible for proving that the delivered file matches the approved submission.

Stage four: retrieve evidence, then separate approval from delivery

A submission that eventually succeeds still needs durable evidence. Store the submission identifier, artifact digest, source revision, tool version, authentication reference, and final status in the CI record. Avoid putting secrets into the same metadata object.

For API-based pipelines, retrieve the diagnostic record through the documented Get Submission Log endpoint. The log should be linked to the exact artifact submitted, not only to a branch name or build number. If the service reports rejection, preserve the log and stop the release. Do not automatically retry the same rejected artifact without classifying the cause.

For notarytool, a Mac job can retrieve a log using the submission identifier and the protected credential profile:

xcrun notarytool log <SUBMISSION_ID> \
  --keychain-profile <KEYCHAIN_PROFILE>

The placeholder is intentional. A production pipeline should inject the value from the current job rather than hard-code it in a repository file.

The failure exit conditions should be explicit:

Submission authentication fails: stop and route to credential diagnostics.
The service rejects the artifact: stop and retain the service log.
The polling job is interrupted: resume from the submission identifier rather than submitting an untracked duplicate.
The artifact digest does not match the approved build: stop before stapling.
A later local validation fails: mark the release failed even if the service accepted the submission.

A remote Mac is especially useful when the same publishing workflow must continue after a controller restart. The controller can recover the job record and request the Mac worker to resume a known submission or validate a known artifact. That is safer than relying on an engineer to remember which file was submitted.

Do not promote “accepted by Apple” to “ready for users.” Approval is a service result. Delivery readiness is a separate result that includes the final file, ticket handling, local validation, and traceable release evidence.

Stage five: staple and validate the final distribution file

The post-notarization stage is where many Linux-first designs become incomplete. Depending on the product format and distribution policy, the ticket may need to be stapled to the application or package. The operation is performed against the final distribution object, not an earlier temporary archive.

On a Mac worker, the pipeline can use Apple’s stapling and validation tools in a controlled step:

xcrun stapler staple <FINAL_ARTIFACT_PATH>
xcrun stapler validate <FINAL_ARTIFACT_PATH>

The Apple packaging documentation should be checked for the product format and packaging assumptions. The notarization workflow guide should remain the authority for the current sequence.

The final verification job should test the file that will actually be uploaded to the release page, update channel, or customer portal. Do not validate only the archived application if users will receive a disk image or installer package.

A useful Mac-side validation sequence can include:

codesign --verify --deep --strict --verbose=2 <APP_PATH>
spctl --assess --type execute --verbose=4 <APP_PATH>
xcrun stapler validate <FINAL_ARTIFACT_PATH>

These commands are checks, not a promise that every product type uses an identical validation sequence. The pipeline should record the product format and select the relevant checks. If the distribution object changes after validation, the job must repeat the checks.

This is the strongest reason not to collapse the whole workflow into “Linux can call the API.” Linux may coordinate the submission, but a real Mac remains the practical location for Apple-specific signing, stapling, and local validation when those steps are part of the release contract.

Remote Mac CI becomes the right choice under these conditions

Use the following decision branches before committing to a topology:

If the team starts from Xcode source, builds Apple-specific targets, or creates the signed package on every release, choose a Mac build worker.
If the team already owns a reproducible signed artifact and only needs service submission and status retrieval, evaluate the Apple Notary API from the existing controller.
If Developer ID keys must remain isolated from the general CI fleet, place the signing job on a restricted remote Mac.
If the product requires stapling or Apple command-line validation after approval, keep a Mac in the post-notarization path.
If releases are infrequent and the team can tolerate queued access, choose an on-demand Mac publishing node and test its clean-state setup every time.
If builds and releases run continuously, choose a dedicated remote Mac CI worker with controlled access, persistent toolchain configuration, and restart recovery.
If the pipeline must support both Linux-native work and macOS-only delivery, use a Linux controller with a remote Mac worker rather than forcing either system to perform the other’s role.
If the team cannot prove credential cleanup, artifact identity, or recovery after interruption, delay production rollout and run a complete trial with a non-release artifact.

This decision list also answers how a remote Mac enters an automated signing and notarization workflow: the controller submits a job, the Mac worker prepares or signs the artifact, the selected submission path communicates with Apple, and the Mac worker performs any required stapling and final validation.

A two-node trial should come before production adoption

Before selecting a long rental period, run one end-to-end rehearsal with a general CI node and an isolated remote Mac. The goal is not to show that one submission succeeded. The goal is to prove that the pipeline can recover and explain every state transition.

The trial should cover:

Build an artifact from a fixed source revision.
Transfer the artifact through controlled storage.
Sign it on the Mac worker with protected credentials.
Submit through either notarytool or the Apple Notary API.
Record the submission identifier and retrieve the diagnostic result.
Staple and validate the final distribution file when required.
Restart the controller or interrupt the worker, then resume from recorded state.
Confirm that a changed artifact cannot pass using an old approval record.
Remove temporary files and verify the keychain state after completion.
Provide a manual takeover path for rejected submissions.

The trial should end with a binary release decision. Either the final file passes every required check and its evidence is stored, or the pipeline remains non-production. A green upload job without final-file validation is not an adequate acceptance result.

The deployment choice in one view

Deployment pattern	Best fit	Mac responsibilities	Main limitation	Score
Linux-only controller with Apple Notary API	Existing signed artifacts and service-side submission	None, unless later validation is added	Cannot replace Mac-specific build, signing, stapling, or validation by assumption	3/5
Dedicated remote Mac CI worker	Frequent builds, signing, packaging, and releases	Build, Developer ID signing, Apple tooling, stapling, final checks	Requires credential isolation and worker maintenance	5/5
Shared Mac worker	Small teams with low release concurrency	Same as a dedicated worker	Stronger cleanup, queue, access, and account controls are required	3/5
Linux controller plus on-demand remote Mac	Infrequent releases and controlled publishing	Only the Mac-specific stages	Cold-start and recovery procedures must be tested before release	4/5
External signing plus Linux submission	Teams with a separate signing service and existing governance	Depends on the external signer	More artifact boundaries and failure handoffs	3/5

The scores are architectural fit ratings, not benchmark results. They reflect how completely each option covers the stated macOS release responsibilities.

For teams comparing ownership with access, a remote Mac rental plan can be useful for the trial stage because it avoids buying a machine before the pipeline’s actual Mac-only requirements are known. The decision should still be based on artifact tests, credential controls, recovery behavior, and release frequency rather than on a submission demo alone.

A Linux-only design is attractive because it centralizes orchestration and may reuse existing runners, but it leaves signing, packaging, stapling, and Apple-tool validation as unresolved dependencies. Buying and maintaining a Mac mini gives physical control, yet it also creates hardware procurement, network access, patching, and availability work. A remote Mac provides the Mac execution boundary without forcing the team to commit to physical hardware first, and it can be expanded from an on-demand publishing node to a longer-lived CI worker after the trial proves the workload.

The practical recommendation is therefore conditional: keep Linux in charge of orchestration when it already fits the organization, but preserve a real Mac wherever the release contract includes Apple-specific construction, Developer ID signing, stapling, or local validation. Start with one isolated remote Mac, test the complete chain with real artifacts, and choose a longer rental cycle only after restart recovery and credential isolation pass the acceptance checks.