Release decision: If your existing Xcode pipeline builds and signs on macOS, keep notarytool. Use the Notary API only when submission and status checks need to run from Windows or Linux. This week, map your release milestones before changing tools: build, sign, submit, inspect the result, staple if required, and verify the deliverable.
This guide is for independent developers distributing macOS apps outside the App Store and deciding where notarization belongs.
It also suits teams assessing Windows or Linux release runners, plus the people responsible for signing credentials and final release checks.
SECTION 01 The boundary between notarization and release
The short answer to “does Xcode notarization need a Mac?” depends on which part of the process you mean. Apple supports both notarytool and the Notary API for interacting with its notarization service. Apple also says the API can remove the macOS dependency for that service interaction. That does not make the full macOS release pipeline portable.
Keep these responsibilities separate:
- Build: Produce the app or package. Xcode builds belong in a supported macOS toolchain; an API call does not supply Xcode or a Mac build environment.
- Sign: Apply the signatures and distribution credentials your software requires. Notary submission does not sign an unsigned artifact for you.
- Submit: Send the prepared software to the notarization service. This is the stage the Notary API can move into a Windows or Linux pipeline.
- Check status and inspect logs: Determine whether the submission was accepted or needs attention. The API supports these service interactions.
- Staple and validate: Attach a ticket where your delivery process requires one, then check the actual release artifact. A successful submission alone is not proof that these tasks are done.
Apple's Notary API overview describes its service role. Apple's distribution preparation guidance covers the broader preparation expected before distributing an app. Use those boundaries to avoid the common mistake of treating “notarized” as shorthand for “built, signed, stapled, and ready to ship.”
SECTION 02 Existing Xcode teams: keep the Mac-native path
If Xcode already builds and signs your app on a Mac, notarytool is generally the lower-complexity choice. It fits into the same environment that owns the project, signing setup, and release artifacts. Your pipeline can hand the prepared software to the command-line workflow, then collect the result and logs without introducing a separate HTTP client and API credential lifecycle.
That choice is not a claim that the API is inferior. It is a boundary check: if your release remains Mac-based, adding an API integration may create more credential handling, request monitoring, and failure recovery without removing the Mac tasks you still need. Apple documents notarytool in its notarization workflow guidance and also describes customizing the notarization workflow. Compare those options against your existing automation rather than rebuilding a functioning release path for cross-platform appearance.
The macOS Command Line Tools are also a separate environment requirement, not a feature delivered by the Notary API. Apple's Command Line Tools installation documentation explains that they are installed as a macOS developer toolset. If your pipeline relies on Apple's local command-line tooling for build, signing, or stapling, an API endpoint does not replace that toolset.
Milestone check: Keep notarytool when the Mac runner already owns the release artifact and the only unmet need is a reliable submission result.
SECTION 03 Windows and Linux teams: move only the service interaction
A Windows or Linux pipeline may be able to handle the notarization service exchange through the Notary API, without running that exchange on macOS. Apple documents the API for submitting software, checking submission status, and retrieving logs. Its web submission instructions describe the submission process and its upload handoff.
The documented operations make the API's scope concrete. The workflow includes creating a submission, uploading the requested artifact, checking the submission record, and obtaining its log. The API reference uses operations such as POST /v1/submissions and submission-specific status and log requests. Those are service operations; they are not equivalents of xcodebuild, code signing, or stapler.
That distinction matters if your team hears “Notary API works without macOS” and concludes that the full release can move to a Linux runner. You still need a valid macOS app artifact that meets Apple's signing and notarization requirements. You also need to decide where ticket stapling and final package validation occur. If those steps use Apple's macOS tools, keep a Mac stage available even when a non-Mac runner submits the software.
The API path also introduces explicit authentication and upload-secret responsibilities. Apple documents JWT authentication for API access and a temporary upload handoff as part of the web submission process. Treat the private key and upload credentials as release secrets: restrict access to the runner that needs them, keep them out of source control and console output, and rotate or revoke access according to your team's credential policy. Do not copy a reusable secret into a build log to make a failed request easier to debug.
Credential boundary: A temporary upload credential is not a substitute for protecting the API signing key. Keep each secret available only to the step that needs it, and avoid saving request headers or credential-bearing responses in artifacts.
Choose a cross-platform submission stage only if its operational benefit is real—for example, the organization already centralizes release orchestration outside macOS. If the artifact still has to return to a Mac for stapling and acceptance, include that transfer and handoff in the design. A pipeline is not simpler merely because one command moved to another operating system.
SECTION 04 External build systems: compare the replaceable step
Some developers generate macOS software through a build system outside Xcode, while a separate release pipeline handles distribution. In that arrangement, compare notarytool with the Notary API specifically as ways to interact with the notarization service. Do not compare them as if either tool creates a valid, signed macOS product from arbitrary build output.
Start with the artifact contract. Confirm that the external system produces the exact package format your release process expects and that its signing state meets Apple's requirements. Then identify which runner can securely access that artifact. If it is already available on a Mac with the necessary Apple tooling, notarytool may keep the release path direct. If a Windows or Linux orchestrator must own the submission and service polling, the API may fit better, provided the required Mac-only operations remain assigned to a suitable stage.
Apple's documentation for custom notarization workflows is useful here because a custom workflow can separate service interaction from other release responsibilities. Sketch the handoffs before writing integration code:
- Where is the signed artifact stored, and which runner can read it?
- Which component makes the notarization request?
- Where do the submission result and diagnostic log go?
- Which component staples the ticket, if your delivery plan requires stapling?
- Who verifies the final app or installer users will download?
This short design exercise often settles the tool choice. If the team cannot identify a clear owner for credentials, logs, and the final artifact, a new API integration will add an unsupported seam rather than remove one.
SECTION 05 Release acceptance: submission is not delivery
A notarization result is one checkpoint, not the final acceptance test. A release owner should verify the result, read any relevant log, and confirm that the exact deliverable passes the team's distribution checks. Apple's guidance on resolving common notarization issues is a reference for diagnosing failures; use the reported issue to fix the artifact or workflow rather than treating a retry as proof of a clean release.
Ticket stapling deserves its own milestone. If your distribution method calls for a stapled ticket, plan for a macOS environment with the appropriate Apple tooling to perform and validate that operation. The API's submission and status functions do not imply that the ticket has been attached to the file you will ship. Keep the downloaded or transferred release artifact traceable through the handoff, then test that artifact—not a nearby build with a similar name.
A practical release record should connect the submission identifier, its result, the log used for diagnosis, the artifact identity, any stapling result, and the final acceptance outcome. This is not extra paperwork for its own sake. It lets you distinguish a rejected submission from a passed submission followed by a failed packaging or handoff step.
SECTION 06 Decision conditions for choosing the tool
Use these branches to make the choice before you edit the release pipeline:
- If Xcode already builds and signs on macOS, and your release team can submit from that environment, choose
notarytool. Keep the current Mac-native chain unless a specific requirement justifies the API integration. - If a Windows or Linux runner must own submission, status checks, or log retrieval, evaluate the Notary API. Keep build, signing, stapling, or acceptance tasks on macOS wherever your actual toolchain requires them.
- If an external build system produces the artifact but a Mac runner owns release preparation, compare both service-interaction options. Prefer the one that fits the runner and credential controls already in place.
- If the team cannot protect the API key, isolate upload credentials, or preserve artifact identity across runners, do not move submission yet. First fix ownership and secret handling; otherwise the new integration creates release risk.
- If your delivery process requires ticket stapling or validation with Mac tools, retain access to a Mac even when submission is cross-platform. The API changes where service calls run, not the rest of your acceptance process.
Before implementing a change, validate the design with a small release candidate. Confirm that the existing artifact can be submitted through the chosen route, that the team can retrieve and understand the result, and that the final deliverable passes the checks you actually use. Keep the established route as a rollback until the replacement has completed those milestones.
SECTION 07 FAQ
Can I run notarytool on Windows or Linux?
Treat notarytool as a macOS command-line tool, not a cross-platform client. Apple documents it as part of the Xcode command-line tools workflow, so a Windows or Linux runner should not be assumed to execute it natively. If only submission and status checks must leave macOS, assess the Notary API; keep other Mac-dependent release stages on a Mac.
Can the Notary API replace notarytool for macOS app notarization?
It can replace the service-interaction portion of a workflow: submitting software, checking submission status, and retrieving logs. It does not build or sign your app, staple a ticket to the delivered artifact, or verify that the final package is ready for users. Compare the two by pipeline ownership and operational needs, not by treating them as complete release systems.
Do I still need stapler if I submit notarization from a non-Mac system?
A successful API submission does not mean the ticket has been stapled to your app or installer. If your delivery plan requires a stapled ticket, schedule that operation as a separate release milestone and use an appropriate macOS environment with Apple's tooling. Then test the exact artifact you intend to distribute rather than relying only on the submission result.
When should an existing Xcode pipeline switch to the Notary API?
Keep notarytool when your build, signing, and release work already runs on macOS and the command-line flow meets your needs. Consider the API when a Windows or Linux pipeline must own submission, status polling, or log retrieval, and you can safely manage its signing key and upload credentials. Do not migrate just to make an otherwise Mac-based release appear cross-platform.
SECTION 08 Choosing where your Mac stage belongs
A Windows or Linux submission runner can reduce the need to place the notarization service call on a Mac, but it adds API credential custody, upload handoffs, and another place to inspect when a release fails. A local Mac keeps Xcode and native release tools together, but tying up your own hardware for a task that runs only during releases can mean upkeep and a machine unavailable for other work.
If you need a Mac only for build, signing, stapling, or acceptance milestones, a remote Mac can keep those operations available without making it the only way to submit notarization. Review VPSNIX remote Mac access guidance and compare the available plans against your release frequency and access requirements. The right choice is the one that keeps each artifact and credential under a clear owner; renting a Mac is an option for the Mac-dependent stages, not a requirement imposed by the Notary API.