How to Set Up Apple notarytool Enterprise CI: 2026 Deployment Guide

Apple documents an App Store Connect API key as using three components: an issuer ID, a key ID, and a private key (Apple’s API key setup). For Apple notarytool enterprise CI, keep the build, signing, and any Xcode- or stapler-dependent work on a verified macOS environment; the Notary API may replace some submission and status-query operations, but not the Mac build workflow.

Who should use this guide: Teams distributing macOS software outside the Mac App Store with Developer ID.
IT and platform teams defining CI permissions and credential handling.
Release engineers responsible for notarization evidence and the final package.

Key takeaway: Treat notarization as a chain of verifiable artifact states, not a single successful CI command.

Define the distribution path before changing the pipeline

First establish whether the release is a macOS app, installer package, disk image, or another supported container. The packaging choice affects what you submit and what you can staple later. Apple’s notarization guidance sets the context: notarization is a pre-distribution check for applicable software, not App Review and not a substitute for your own release acceptance.

For Mac App Store distribution, do not reuse the same Developer ID notarization plan by default. The workflow here concerns software distributed outside the store. Confirm the distribution channel first, then make the intended end-user artifact—not a convenient intermediate—the object your team validates.

Map the artifact to the release check

Apple documents supported workflow and artifact considerations in its custom notarization workflow guide. Match the artifact choice to that guidance rather than assuming every file that can be uploaded is equally suitable for stapling.

A common hidden cost is artifact ambiguity. If one job signs an app, another repackages it, and a third uploads a container without recording the relationship, a green build cannot prove which bytes Apple reviewed. Keep a stable reference to the source revision, build task, signing identity, and exact submitted file.

Build a traceable Developer ID artifact on Mac CI

The build stage should produce a release candidate with enough evidence for another engineer to identify how it was made. Record the source revision, CI job reference, signing identity, export or packaging settings, and artifact checksum alongside the output. This makes it possible to connect an Apple response to the actual file that entered the pipeline.

For distribution outside the Mac App Store, verify that the release uses the intended Developer ID signing identity. Check the applicable code-signing and Hardened Runtime requirements against Apple’s Developer ID distribution documentation and Hardened Runtime configuration guide. The exact settings depend on the product and its capabilities; do not copy entitlements from a development build without confirming why each one is needed.

A development signature is not a release acceptance decision. Your CI should check the actual exported artifact, including its signature and runtime configuration, rather than infer readiness from an Xcode build job’s success. If Xcode Organizer fits the team’s manual release process, it can be useful for a controlled release. For repeatable team automation, scripted build and verification steps make inputs and outputs easier to audit. Either route still needs a clear link between the signed artifact and the release record.

Release control: If the artifact changes after notarization submission, do not assume the earlier result proves the new file is ready. Re-run the relevant checks against the artifact you will distribute.

Set authentication and permissions before enabling submissions

Choose the authentication method that matches your organization’s account and CI controls. Apple documents notarytool credential options in its workflow material, including App Store Connect API key credentials and Apple account credentials. Keep those methods distinct in configuration and documentation; do not combine flags or assumptions from one route with another.

The App Store Connect API key documentation explains key creation and permission considerations. Apply least privilege according to your organization’s policy, and ensure the people responsible for the key understand how access is reviewed and withdrawn.

Store secrets in your CI platform’s protected secret mechanism or another approved credential service. Inject them only into the job that needs them. Avoid placing a private key or password in a checked-in script, command-line output, build artifact, or debug log. Review shell tracing and failure output as well: a job can expose a secret even when the script does not intentionally print it.

Separate who can modify the pipeline from who can access notarization credentials. If every build job can read the signing and notarization material, a pull-request job may have broader access than its purpose requires. Define the trusted branch or release condition that grants access, name the credential owner, and document how access is removed when a key is rotated or a team member changes role.

Submit the exact artifact and retain its submission ID

Use notarytool’s documented submit flow for the artifact you selected, with credentials supplied through the approved mechanism. Apple’s custom notarization workflow documentation describes the command-line workflow, including checking a submission and retrieving its log. Save the submission ID as a CI output or release record; it is the handle your team needs to connect the upload to Apple’s later status and diagnostic information.

Do not equate a completed upload with completed notarization. Distinguish submission acceptance or processing from the final result, and make the pipeline wait for or explicitly query the result before continuing. A job that exits after upload can report success while leaving the release state unresolved.

The Notary API is an alternative for parts of this interaction. Apple documents API submission through its web submission guide and submission endpoint documentation. Use those references to validate the request, authentication, and response handling. The API can change how your system submits and checks work; it does not build the app or eliminate Mac-based steps your release requires.

For an Invalid result, retrieve Apple’s log using the recorded submission ID before changing settings at random. Match each reported issue to the submitted artifact. Investigate signing and Hardened Runtime configuration, the packaging boundary, and any specific file or entitlement Apple identifies. Retain the log with the artifact reference and build context so that a later retry can be compared rather than reconstructed from memory.

Check the ticket and final package before release

A notarization result is one part of distribution acceptance. The release pipeline should also verify that the result belongs to the intended artifact, that required ticket handling is complete, and that packaging has not replaced or altered the item that passed review. Define those checks as explicit gates, then retain their outputs with the release record.

Use stapler where the distribution format and Apple’s guidance call for it. Apple’s workflow documentation describes stapling for applicable deliverables and the supported process. A ZIP file is not itself a stapling target: if your delivery uses a ZIP, plan the workflow around a supported item such as the app before packaging, then verify the resulting archive and contents. Do not mark a release complete solely because the notarization service accepted a submission.

The final validation should cover the object that will reach users. Check the package’s integrity and expected contents after ticket handling and packaging. Record the result of the relevant validation commands, the Apple submission status, and the log when a submission needed investigation. Your organization’s release gate may also require a human approval; distinguish that internal policy from Apple’s technical response.

Questions that affect the workflow

Can I use a development signature for distribution?

Use the release candidate’s intended Developer ID signature for the distribution workflow and verify it on the artifact that will be submitted. A successful development build does not prove that the exported package meets distribution requirements. Check the signing identity, Hardened Runtime configuration, and any product-specific entitlements against Apple’s documentation before you open the notarization gate.

Should I use Xcode Organizer or a scripted release?

Choose based on who must run the release and what evidence the team needs. Organizer can fit a human-controlled release process, while scripted Mac CI can make repeated build, submission, and verification steps easier to trace. Neither choice removes the need to identify the final artifact, retain the submission ID, and confirm the result before distribution.

Which CI tasks should receive notarization credentials?

Restrict credential access to the trusted submission and status-check tasks that require it. Build jobs that only compile or run tests should not automatically inherit notarization secrets. Use protected CI secrets, control which branches or release events can access them, and inspect logs for accidental disclosure. Assign an owner who can review access and coordinate credential rotation.

What belongs in the failure record?

Keep the submission ID, Apple’s returned log, the exact submitted artifact or a reliable reference to it, its checksum, the source revision, and the signing identity. Add the CI job context and the fix applied before retrying. This evidence lets you distinguish a packaging or signing defect from a pipeline configuration issue and makes repeated failures easier to compare.

Decide which stages need a Mac before approving the runner

A useful assessment compares stages, not slogans about “cloud CI” or “API-first” architecture. Build, Xcode-dependent work, signing, and stapler operations need validation on the macOS environment your pipeline will actually use. Submission and status queries may be handled through notarytool or evaluated for the Notary API. Security depends on your access model, host controls, and credential handling; do not infer it from the interface alone.

Decision conditions

• If a release stage depends on Xcode, macOS signing tools, or stapler, keep that stage on a Mac CI worker and validate it with a real release candidate.
• If you only want to change submission or status-query handling, evaluate the Notary API against Apple’s documented authentication and request flow; keep the Mac-dependent build and artifact steps.
• If the team cannot restrict credential access or preserve the submission-to-artifact link, pause automation and fix those controls before widening access.
• If you distribute a ZIP, plan ticket handling for the supported item inside the release process; do not schedule stapler against the ZIP itself.

Run a complete pilot before approving a worker model. Execute the build, signing checks, submission, final status confirmation, log retrieval path, ticket handling, and final package validation. For each stage, name the input, output, owner, and retained evidence. This shows whether the bottleneck is a missing Mac tool, a credential boundary, an unclear artifact, or a release gate that was never defined.

If you are evaluating remote capacity, compare the actual delivery details with your required Xcode and stapler work, access model, and release controls. You can review VPSMAC’s Mac node options and the VPSMAC service overview, then confirm the details relevant to your workflow before selecting a host. Do not infer an unverified security control, performance level, or service commitment from the fact that a Mac is remotely accessible.

A self-managed Mac can be the better fit when you need direct physical access, tightly controlled local infrastructure, or stable long-running workloads that justify owning and maintaining the machine. Its trade-offs include upfront capital, replacement and repair planning, and ongoing administration. Remote Mac rental can be worth assessing when you need temporary release capacity without buying another machine, but you still need to verify delivery, access, and operational fit against your own acceptance criteria.

Before you approve the runner, list the steps that must use Xcode, notarytool, or stapler, then compare those requirements with the remote Mac details you can actually verify. If a short-term or changing workload makes purchasing and maintaining another Mac disproportionate, VPSMAC may be an option to evaluate for that capacity; keep the decision conditional on a successful end-to-end pilot, not on an assumed security or cost advantage.