How to Integrate macOS App Notarization into Remote Mac CI? 2026 Guide

Set the release boundary before changing CI

This workflow covers Developer ID distribution outside the Mac App Store. Notarization is not App Review, and a successful notarization submission does not mean the delivered application has passed a complete release test. Apple describes notarization as a check for software distributed outside the Mac App Store; App Store delivery follows a different process. See Apple’s overview of notarizing macOS software.

Keep the release chain explicit:

• Prepare a signed application or other release artifact.
• Submit the artifact for notarization and retain the submission record.
• Review the processing result and, when needed, its log.
• Handle the ticket for the selected distribution format.
• Check and test the actual file intended for distribution.

The handoff between stages matters. An archive, an exported application, and a final ZIP or disk image are not necessarily the same file. If CI records only “notarization succeeded,” a later change in export settings or packaging can break the relationship between the accepted submission and the file users download.

Apple’s macOS distribution signing guidance explains the signing context for distributed Mac software. Preserve the relationship between that signed output and the artifact submitted for notarization instead of treating every build product as interchangeable.

Prepare signing and artifacts on the remote Mac

Before adding a submission command, confirm that the remote Mac build produces a valid distribution artifact. Apple’s signing guidance describes Developer ID distribution, Hardened Runtime, and secure timestamps as relevant signing requirements for this flow. Check the project’s actual signing configuration and current official instructions; do not copy a certificate name, Team ID, or entitlement value from an unrelated project.

Keep the build and packaging stages separate in the pipeline record. An Xcode archive is an intermediate build product. An exported application, installer package, ZIP archive, or disk image may be a later submission or delivery artifact, depending on the release design. Apple’s Mac software packaging guidance describes distribution packaging options. Verify the precise notarization and ticket-handling steps for the format actually being shipped.

A useful preflight record contains:

• The source revision and build job reference.
• The location and identity of the archive, export, and final package.
• The signing verification result for the artifact selected for submission.
• The signing configuration and relevant entitlements used for that build.
• The packaging step that produced the file intended for distribution.

How should macOS code signing be checked before notarization?
Run the project’s existing signature verification against the exact exported artifact that CI will submit, and retain the result with the build record. If the check reports a problem, resolve it at the signing or packaging stage rather than treating notarization as a repair step. For app bundles that contain helper tools or other embedded code, inspect the complete signed product, not just the outer application bundle. Apple’s notarization overview describes the prerequisites to check before submission.

The key decision is whether the pipeline has a stable, traceable file to submit. If the build job silently re-exports or repackages an artifact after the signature check, the recorded evidence no longer describes the submitted file.

Choose a credential path and make the first submission

Confirm that the selected Xcode installation or Command Line Tools on the remote Mac can invoke notarytool before wiring the command into a release job. Apple’s migration guidance states that, from November 1, 2023, notarization uploads through altool or Xcode 13 and earlier are no longer accepted; Apple directs scripted workflows toward notarytool. See Apple’s migration note for the notarization tool. Check tool availability on the actual build host rather than assuming every installed toolchain behaves the same.

Credentials should enter CI through a controlled secret mechanism. A Keychain profile can provide a named credential reference for notarytool; the CI secret store is responsible for restricting who can inject or change the underlying authentication material. Neither responsibility belongs in source control. Apple’s custom notarization workflow guidance describes credential setup and scripted submission. Follow its current authentication instructions for the account and team configuration in use.

Do not place passwords, app-specific passwords, private keys, tokens, Team IDs, or other account identifiers in repository files, command-line examples, or verbose logs. Use placeholders in pipeline configuration and reference the secret through the CI system’s protected mechanism. Confirm that shell tracing and diagnostic output cannot expose the injected value.

A submission command can be added only after credential setup and artifact selection are verified. Apple’s custom workflow documentation provides the current notarytool syntax and options. The pattern below deliberately leaves the credential profile and artifact as placeholders; check the linked documentation before using it in a live pipeline.

xcrun notarytool submit "<path-to-release-artifact>" \
  --keychain-profile "<notary-profile>" \
  --wait

The job should capture the command’s exit result and submission identifier without printing secret material. Store the identifier with the source revision and artifact identity so a later status check can be tied to the correct release candidate.

How should a remote Mac CI job save and use notarization credentials?
Keep reusable credentials in a protected secret mechanism, then make them available to the release job only when needed. A Keychain profile can be the local reference used by notarytool, while CI controls who can create or access that profile. If the remote Mac is shared across jobs, isolate access to the relevant account and ensure cleanup and logging rules do not expose secrets.

Review the result, status, and failure evidence

A submitted file is not automatically ready to distribute. Retain the submission identifier, query or wait for the processing result, and retrieve the corresponding log when the result is not accepted or includes warnings that need investigation. Apple’s Notary API documentation describes submission and status resources. Its troubleshooting guidance can help classify common problems.

A status check can use the submission identifier returned by the submit step. Follow Apple’s current command documentation for the exact options:

xcrun notarytool info "<submission-id>" \
  --keychain-profile "<notary-profile>"

For a failed submission, retrieve the processing log before changing the pipeline:

xcrun notarytool log "<submission-id>" \
  --keychain-profile "<notary-profile>"

Store the resulting evidence with the release job. Avoid copying account credentials into the log bundle, and redact values that identify internal systems if those logs will be shared outside the release team. For common rejection causes, consult Apple’s notarization troubleshooting guidance.

What must be checked after a notarytool submission succeeds?
Review the final processing result, retain the submission identifier, and inspect warnings or processing log entries that affect the artifact. Then confirm that the output to be distributed is the same release candidate, or a correctly derived package, that the pipeline intends to ship. A successful submission is one piece of release evidence, not the final delivery sign-off.

Do not diagnose a remote Mac or network failure from a single error string. First separate signing, permissions, packaging, credential, and service-response evidence. If the log points to an invalid signature or unsupported structure, reproduce that check against the saved artifact before changing node settings. If the evidence instead concerns authentication, inspect the secret injection and profile access path without printing the secret.

Handle tickets according to the distribution format

Ticket handling depends on the artifact being distributed. Do not apply the same assumption to an application bundle, ZIP archive, disk image, and installer package. Use Apple’s current custom notarization workflow guidance to confirm the process and supported formats for the release design.

For a format that Apple’s current guidance supports for stapling, run the appropriate stapler operation against the intended artifact. The command pattern below uses a placeholder. Verify the target and supported format against Apple’s documentation before running it in release automation.

xcrun stapler staple "<path-to-supported-artifact>"
xcrun stapler validate "<path-to-supported-artifact>"

Keep the checks distinct:

• Processing result: the outcome recorded for the notarization submission.
• Ticket handling: whether the ticket is attached where the selected format supports it.
• Signature validity: whether the distributed application remains correctly signed.
• Delivery behavior: whether the downloaded file can be installed or launched as intended.

How can the team verify that a ticket is stapled?
For an artifact supported by Apple’s stapling workflow, run stapler validate against the exact file that will be distributed and retain the command result. If the format does not use stapling in the same way, follow Apple’s current format-specific instructions instead of treating a missing stapled ticket as proof of failure. A local validation result also does not replace a test of the delivered download.

Accept the release only after an end-to-end test

Before enabling unattended publication, run an isolated release task through the same build, signing, submission, ticket, and packaging path intended for production. Use a release candidate that can be discarded if the checks fail. The purpose is to verify the complete chain, including which file was submitted and which file was tested after packaging.

The release record should let an engineer connect the source revision to the build job, signed artifact, notarization submission, processing log, ticket operation, and final downloadable file. A mismatch at any link is a hold condition: rerun or investigate the affected stage instead of inferring that the release is safe from a single green CI status.

Use these decision branches to choose the release control:

• If the signed artifact, submission record, processing result, ticket check where applicable, and download test all refer to the same release candidate, then allow the pipeline to publish under its normal approval rules.
• If the notarization result is accepted but the final packaged file has not been checked, then hold publication and validate that final file.
• If a warning or failure has no reviewed log entry and an assigned cause, then keep the job blocked and investigate the recorded evidence.
• If the job cannot access credentials without exposing them or granting excessive permissions, then stop automation and revise the secret-injection boundary before retrying.
• If the process depends on a person manually copying artifacts or submission identifiers without an audit trail, then retain a human approval step until those handoffs become traceable.

Include credential rotation, retry ownership, log retention, and recovery responsibility in the release runbook. A retry should start from the stage identified by evidence; blindly rebuilding and resubmitting can replace the artifact under investigation and weaken the audit trail. The Notary API reference can help teams build additional submission tracking around the command-line workflow.

A remote Mac CI workflow is a good fit when the release requires macOS tooling and the team can control signing assets, secret access, and final-artifact validation. If the current setup relies on a Linux host for every stage, it cannot replace Mac steps that depend on Apple’s distribution tooling. If a developer already owns a suitable Mac and needs only occasional release automation, a local build host may be simpler; a remote environment adds access controls, network dependence, and operational handoffs that also need review.

For teams without a suitable Mac execution environment, NodeMini’s remote Mac options can be assessed with a real release task before changing the production pipeline. Check the required Xcode toolchain, signing-asset access, secret controls, and ability to retrieve logs and final artifacts. The NodeMini site provides a starting point for reviewing the remote Mac environment. Make the decision only after an end-to-end validation, not from the notarization submission result alone.