Apple notarytool in der Unternehmens-CI einrichten: Bereitstellungsleitfaden 2026

Ein ZIP-Archiv lässt sich nicht direkt mit einem Notarisierungsticket versehen; Apple beschreibt das Stapling für unterstützte Artefakte in der Dokumentation zur Notarisierung von macOS-Software. Planen Sie Apple notarytool in der Unternehmens-CI deshalb als nachvollziehbare Kette aus Build, Signatur, Einreichung, Statusprüfung und Artefaktkontrolle. Schritte, die Xcode oder stapler voraussetzen, müssen Sie in einer macOS-Umgebung prüfen. Die Notary API kann bestimmte Einreichungs- und Abfragevorgänge ersetzen, aber nicht automatisch den Mac-Build.

Dieser Leitfaden richtet sich an Teams, die macOS-Software außerhalb des Mac App Store mit Developer ID verteilen.
IT- und Plattformverantwortliche erhalten Kriterien zur Trennung von Signaturschlüsseln, Zugangsdaten und CI-Rechten.
Release-Verantwortliche finden eine Prüflogik für Status, Apple-Protokoll, Ticket und endgültiges Distributionsartefakt.

Vor dem ersten CI-Lauf den Verteilungsweg festlegen

Klären Sie zuerst, welches Objekt Ihr Team ausliefert: eine macOS-App, ein Installationspaket oder ein Disk-Image. Die Notarisierung muss zum tatsächlichen Verteilungsweg und zum einzureichenden Artefakt passen. Ein erfolgreiches Build ist kein Nachweis dafür, dass genau das später verteilte Objekt korrekt signiert und notariert wurde.

Unterscheiden Sie die Wege klar:

• Verteilung außerhalb des Mac App Store: Prüfen Sie die einschlägigen Anforderungen an Developer-ID-Signatur und Notarisierung. Apple beschreibt Developer ID als Signaturweg für Software, die außerhalb des Mac App Store verteilt wird (Apple Developer ID).
• Verteilung über den Mac App Store: Verwenden Sie den dafür vorgesehenen Veröffentlichungsprozess. Setzen Sie diesen Prozess nicht mit dem Notarisierungsweg für externe Verteilung gleich.
• Unterschiedliche Artefaktformate: Legen Sie fest, welches Objekt Apple erhält und welches Objekt Kundinnen und Kunden bekommen. Falls Ihre Pipeline nach der Notarisierung weiter verpackt oder verändert, muss sie anschließend das endgültige Lieferobjekt erneut prüfen.

Notarisierung ist weder App Review noch eine vollständige Release-Abnahme. Sie müssen zusätzlich festlegen, welche internen Freigaben, Dokumentationen und Prüfungen vor der Auslieferung erforderlich sind. Apple beschreibt notarytool als Werkzeug zur Anpassung des Notarisierungsablaufs, zur Statusprüfung und zum Abruf von Protokollen (Apple: Notarisierungsablauf anpassen). Diese Möglichkeiten ersetzen nicht Ihre eigenen Annahmekriterien.

Vor dem Build: Artefakt, Nachweise und Rechte zuordnen

Bevor Sie Befehle in die Pipeline einbauen, definieren Sie die Beweiskette. Ordnen Sie den Quellstand, den Build-Auftrag, die Signaturidentität und das exportierte Artefakt eindeutig einander zu. Ein grüner CI-Status allein sagt nicht aus, ob das freizugebende Paket tatsächlich signiert und zur Notarisierung eingereicht wurde.

Halten Sie pro Lauf mindestens diese Angaben fest:

• Quellstand und Referenz des Build-Auftrags.
• Signaturidentität und verwendete Build-Konfiguration.
• Eindeutige Bezeichnung des eingereichten Artefakts.
• Submission-ID, abschließender Status und Apple-Protokoll.
• Ergebnis von Stapling und Validierung sowie die zuständige Freigaberolle.

Die konkrete Art der Artefaktzuordnung können Sie an Ihre bestehende Nachweisführung anpassen. Entscheidend ist, dass ein späterer Prüfer den Weg vom Quellstand bis zum veröffentlichten Paket nachvollziehen kann. Eine interne Artefaktkennung oder Prüfsumme kann dabei helfen; sie ersetzt jedoch nicht Apples Prüfung oder die Kontrolle des fertigen Pakets.

Planen Sie auch die Rechteverteilung vor dem ersten produktiven Lauf. Ein Build-Auftrag sollte nicht automatisch Zugang zu Notarisierungsdaten erhalten, wenn er keine Veröffentlichung ausführt. Umgekehrt benötigt ein reiner Status- oder Analyseauftrag nicht zwingend Zugriff auf das Signaturmaterial. Diese Trennung ist eine von Ihrem Team einzurichtende Sicherheitsmaßnahme und keine pauschale Zusicherung über die Sicherheit der gesamten CI-Plattform.

Erster Schritt: das für die Veröffentlichung vorgesehene Objekt signieren

Signieren Sie das Objekt, das tatsächlich verteilt wird, und prüfen Sie die Signatur nach dem Export. Kontrollieren Sie die Developer-ID-Signatur, die für Ihren Fall erforderliche Hardened Runtime und den Zeitstempel. Apple erläutert die Hardened Runtime als Konfiguration, die für Notarisierungsabläufe relevant sein kann (Apple: Hardened Runtime konfigurieren). Prüfen Sie die konkreten Anforderungen außerdem anhand der Apple-Dokumentation zur Notarisierung und Ihres Verteilungswegs, statt eine Einstellung pauschal für jede Anwendung vorauszusetzen.

Achten Sie besonders auf Änderungen zwischen Signieren und Einreichen. Wenn ein Verpackungsschritt nach der Signatur Dateien verändert, kann die vorherige Prüfung für das eingereichte Objekt nicht mehr ausreichen. Machen Sie deshalb im CI-Protokoll sichtbar, welches Artefakt in die nächste Stufe übergeht. Die Pipeline sollte eine fehlgeschlagene oder nicht eindeutig zuordenbare Signaturprüfung als Sperre behandeln.

Eine Entwickler- oder lokale Signatur ist nicht automatisch ein Beleg für ein freigabefähiges Developer-ID-Release. Prüfen Sie die Signaturidentität und den Verteilungsweg, nicht nur den Namen einer Xcode-Konfiguration. Xcode Organizer kann für manuelle oder kontrollierte Veröffentlichungen passend sein. Bei wiederholbaren Teamabläufen benötigen Sie darüber hinaus eine dokumentierte Skript- und Freigabelogik, die denselben Prüfpfad auf jedes Release anwendet.

Zweiter Schritt: Zugangsdaten begrenzen und CI-Ausgaben prüfen

Apple dokumentiert unterschiedliche Authentifizierungswege. Behandeln Sie Apple-Account-Zugangsdaten und App Store Connect API-Schlüssel nicht als austauschbare Bestandteile einer einzigen Konfiguration. Wählen Sie den für Ihren Ablauf vorgesehenen Weg und notieren Sie, welche Aufgabe darauf zugreifen darf. Die Erstellung und Berechtigungen von API-Schlüsseln beschreibt Apple in der Dokumentation zu App Store Connect API-Schlüsseln.

Speichern Sie Zugangsdaten nicht als Klartext in Skripten, Repository-Dateien oder dauerhaft aufbewahrten Build-Ausgaben. Verwenden Sie die geschützte Geheimnisverwaltung Ihrer CI-Umgebung, begrenzen Sie den Zugriff auf die tatsächlich benötigten Release-Aufträge und bestimmen Sie eine verantwortliche Rolle für Berechtigungen und Rotation. Die konkrete Speicherlösung hängt von Ihrer Plattform und Ihren internen Vorgaben ab; stellen Sie sie nicht als von Apple bereitgestellte Funktion dar.

Prüfen Sie nicht nur erfolgreiche Läufe. Debug-Ausgaben, Shell-Fehler oder ausführliche Protokolle können sensible Werte offenlegen, wenn Skripte sie unbedacht ausgeben. Maskierung hilft nur, wenn die CI-Umgebung die betreffenden Werte richtig erkennt. Testen Sie daher Fehlerpfade mit nicht produktiven Zugangsdaten und kontrollieren Sie, welche Informationen nach einem fehlgeschlagenen Authentifizierungsversuch im Protokoll verbleiben.

Dritter Schritt: einreichen und den Status abwarten

Reichen Sie das signierte Distributionsartefakt mit notarytool ein und speichern Sie die von Apple zurückgegebene Submission-ID. Ein erfolgreicher Upload belegt nur, dass die Übertragung abgeschlossen wurde; er belegt nicht, dass die Notarisierung akzeptiert ist. Lassen Sie die Pipeline den Status nachverfolgen und erst dann fortfahren, wenn ein abschließendes positives Ergebnis vorliegt und das zugehörige Apple-Protokoll geprüft wurde.

Unterscheiden Sie in Ihren CI-Ergebnissen mindestens diese Zustände:

• Eingereicht oder in Bearbeitung: Die Übertragung ist erfolgt, die Freigabe bleibt gesperrt.
• Akzeptiert: Das Notarisierungsergebnis ist positiv; die übrigen Release-Prüfungen sind weiterhin erforderlich.
• Abgelehnt oder fehlgeschlagen: Stoppen Sie die Veröffentlichung und werten Sie das Protokoll aus, bevor Sie einen neuen Lauf starten.

Die Notary API kann bestimmte Einreichungs- und Statusvorgänge anstelle entsprechender notarytool-Aufrufe übernehmen. Apple dokumentiert das Einreichen über die API und den zugehörigen Ablauf (Apple: Software über die Notary API einreichen, Apple: Einreichung über das Web). Prüfen Sie Authentifizierung und Rückgabewerte anhand dieser Unterlagen. Wenn Ihre Software weiterhin auf einem Mac gebaut, signiert oder gestapelt werden muss, entfällt diese macOS-Arbeit nicht durch die Wahl der API.

Fragen aus der Umsetzung in Mac CI

Wie binden Sie notarytool in eine macOS-CI-Pipeline ein?

Führen Sie die Notarisierung als eigene Release-Stufe aus: Erzeugen Sie zuerst das signierte Distributionsartefakt, reichen Sie genau dieses mit notarytool ein und speichern Sie die Submission-ID. Die Pipeline sollte erst fortfahren, wenn der Status geprüft und das Apple-Protokoll ausgewertet wurde. Danach folgen Stapling, Validierung und die Freigabe des endgültigen Pakets.

Wie bleiben Zugangsdaten aus Skripten und Protokollen heraus?

Legen Sie Zugangsdaten nicht als Klartext in Skripten, Repository-Dateien oder Build-Ausgaben ab. Verwenden Sie den für Ihr Team vorgesehenen Apple-Authentifizierungsweg, begrenzen Sie den Zugriff auf die erforderlichen Release-Aufträge und dokumentieren Sie Zuständigkeit sowie Rotation. Prüfen Sie zusätzlich, ob Debug-Ausgaben, Fehlerprotokolle oder Kommandozeilen sensible Werte sichtbar machen.

Was hilft bei einem abgelehnten Notarisierungsergebnis?

Verwenden Sie das Apple-Protokoll zusammen mit der Submission-ID, statt nur die letzte CI-Fehlermeldung zu betrachten. Prüfen Sie, ob das eingereichte Artefakt dem vorgesehenen Release entspricht, ob Developer-ID-Signatur und Hardened Runtime passen und ob die Verpackung Dateien verändert oder ausgelassen hat. Bewahren Sie Protokoll, Build-Referenz und Eingabeartefakt für die Analyse auf.

Welche Prüfung folgt auf die Annahme durch Apple?

Ein akzeptierter Notarisierungsvorgang ist nicht automatisch die vollständige Release-Abnahme. Prüfen Sie den vorgesehenen Verteilungsweg und stapeln Sie das Ticket auf einem unterstützten endgültigen Artefakt, sofern es für dessen Format vorgesehen ist. Ein ZIP-Archiv lässt sich nicht direkt stapeln. Richten Sie den Schritt daher auf das darin enthaltene unterstützte Objekt aus und validieren Sie anschließend das ausgelieferte Paket.

Kann die Notary API einen Mac-CI-Knoten ersetzen?

Nicht pauschal. Die Notary API kann laut Apple bestimmte Einreichungs- und Statusabfragen übernehmen, ersetzt aber nicht automatisch den macOS-Build, die Xcode-Werkzeuge oder erforderliche Stapling- und Validierungsschritte. Entscheiden Sie anhand eines vollständigen Testlaufs, welche Stufen Mac-Werkzeuge benötigen und welche API-Aufrufe sich unabhängig davon betreiben lassen.

Vierter Schritt: Protokoll auswerten, Ticket stapeln und das Paket prüfen

Bei einer Ablehnung ist das Apple-Protokoll der zentrale Diagnosebeleg. Verknüpfen Sie die dortigen Angaben mit dem eingereichten Artefakt und seiner Build-Referenz. Prüfen Sie, ob das erwartete Objekt eingereicht wurde, ob die Signatur zum Verteilungsweg passt und ob die Paketierung nach dem Signieren Änderungen vorgenommen hat. Ein erneuter Upload ohne diese Zuordnung kann denselben Fehler wiederholen, ohne die Ursache einzugrenzen.

Nach einem akzeptierten Ergebnis prüfen Sie, ob das vorgesehene Format das Stapling unterstützt. stapler heftet ein Ticket an unterstützte Objekte; ein ZIP-Archiv kann nicht direkt gestapelt werden. Bei einem ZIP-basierten Verteilungsweg muss der Stapling-Schritt deshalb auf das passende enthaltene Objekt ausgerichtet werden, bevor Sie das Archiv erzeugen, sofern Ihr Ablauf dies erfordert. Apple beschreibt Ticket- und Stapling-Schritte in der Dokumentation zur Notarisierung von macOS-Software.

Führen Sie anschließend eine Validierung des finalen Objekts aus. Kontrollieren Sie zusätzlich, dass das zur Verteilung bestimmte Paket dem geprüften Artefakt entspricht. Die Notarisierung belegt nicht automatisch, dass Release-Notizen, Aktualisierungswege, Berechtigungen oder interne Freigaberegeln erfüllt sind. Diese Punkte gehören in Ihre eigene Abnahme und sollten als separate Ergebnisse nachvollziehbar bleiben.

Entscheidungshilfe: CI-Aufteilung vor dem Rollout abhaken

Gehen Sie die folgenden Prüfpunkte für Ihr Release durch. Markieren Sie jeden Punkt erst dann als erfüllt, wenn ein Pipeline-Test oder ein dokumentierter Nachweis vorliegt.

• [ ] Benötigt der Build Xcode oder macOS-Signaturwerkzeuge? Wenn ja, führen Sie diese Stufen auf einer macOS-Umgebung aus. Wenn nein, prüfen Sie trotzdem, ob das erzeugte Artefakt anschließend auf einem Mac signiert werden muss.
• [ ] Benötigt der Release stapler oder eine macOS-Validierung? Wenn ja, planen Sie diese Schritte auf einem Mac ein. Wenn nein, dokumentieren Sie, warum das konkrete Distributionsformat keinen solchen Schritt erfordert.
• [ ] Soll nur die Einreichung oder Statusabfrage ausgelagert werden? Wenn ja, testen Sie die Notary API als mögliche Alternative zu den entsprechenden notarytool-Aufrufen und belegen Sie Authentifizierung, Rückgabestatus und Protokollzuordnung. Wenn nein, behalten Sie den geprüften notarytool-Pfad bei.
• [ ] Ist der Apple-Status abgeschlossen und das Protokoll ausgewertet? Wenn ja, kann die Pipeline zur Artefaktprüfung übergehen. Wenn nein oder der Vorgang noch in Bearbeitung ist, bleibt die Veröffentlichung gesperrt.
• [ ] Ist das tatsächlich auszuliefernde Objekt geprüft und gegebenenfalls gestapelt? Wenn ja, dokumentieren Sie die Artefaktzuordnung. Wenn nein, wiederholen Sie die nötigen Prüfungen auf dem endgültigen Lieferobjekt.
• [ ] Sind Zugangsdaten auf erforderliche Release-Aufträge beschränkt? Wenn ja, kontrollieren Sie zusätzlich Fehlerausgaben und Rotation. Wenn nein, reduzieren Sie die Zugriffsrechte vor dem Produktivbetrieb.
• [ ] Kann ein Prüfer den Weg vom Quellstand bis zum veröffentlichten Paket nachvollziehen? Wenn ja, liegt ein belastbarer Abnahmenachweis vor. Wenn nein, ergänzen Sie Build-Referenz, Submission-ID, Protokoll und Ergebnis der Artefaktkontrolle.

Das Ergebnis der Liste steuert die Architekturentscheidung: Wenn Xcode, Signatur oder Stapling erforderlich sind, bleibt eine Mac-Umgebung Teil der Pipeline. Wenn nur Einreichung und Statusabfrage ersetzt werden sollen, können Sie die Notary API für genau diese abgegrenzten Aufgaben testen. Wenn auch nur ein erforderlicher Prüfschritt oder Nachweis fehlt, geben Sie den Ablauf noch nicht frei.

Fünfter Schritt: den vollständigen Lauf als Freigabenachweis verwenden

Testen Sie die Pipeline mit einem realistischen Release-Artefakt und protokollieren Sie für jede Stufe Eingabe, Ausgabe und Zuständigkeit. Der Lauf muss Build, Signatur, Einreichung, Statusbestätigung, Ticketbearbeitung und abschließende Artefaktprüfung umfassen. Lassen Sie nicht nur den technischen Erfolg, sondern auch die Zuordnung der Belege kontrollieren: Ein Prüfer muss erkennen können, welcher Quellstand zu welcher Submission-ID und zu welchem ausgelieferten Paket gehört.

Bewerten Sie danach, welche Teile zwingend auf einem Mac ausgeführt werden müssen. Xcode-Build und Signatur können Mac-Werkzeuge erfordern; Stapling muss für das konkrete Artefakt ebenfalls in der passenden Umgebung geprüft werden. Einreichung und Statusabfrage können Sie gegen die Notary API abgrenzen, wenn Ihr Team Authentifizierung und Nachweisführung dafür sauber eingerichtet hat. Diese Aufteilung ist anhand Ihrer Pipeline zu verifizieren und keine allgemeine Zusicherung über die Eignung einer bestimmten Laufzeitumgebung.

Beziehen Sie außerdem Betrieb und Datenzugriff in die Freigabe ein. Prüfen Sie, wer auf den Mac-Knoten zugreifen darf, wie Signaturmaterial bereitgestellt wird und welche CI-Aufträge Zugangsdaten erhalten. Für Unternehmen mit Anforderungen an DSGVO-konforme Prozesse sollten Sie Ihre Datenflüsse und Aufbewahrungsvorgaben selbst dokumentieren; aus der Nutzung einer Remote-Umgebung folgt keine pauschale Compliance-Zusage. Erfassen Sie auch, wie Build-Artefakte, Protokolle und Geheimnisse nach einem fehlgeschlagenen oder abgeschlossenen Release behandelt werden.

Remote-Mac-Betrieb erst nach Prüfung der Anforderungen auswählen

Ein Remote-Mac kann für eine CI-Aufgabe infrage kommen, wenn Ihre Pipeline macOS-Werkzeuge benötigt und Sie Zugriffs-, Daten- und Abnahmeregeln überprüft haben. Er ist jedoch nicht automatisch für jeden Release-Prozess geeignet. Stellen Sie insbesondere fest, wer Signaturmaterial verwenden darf, wie Geheimnisse in einzelne Jobs gelangen und welche Nachweise Sie für Übergabe und Rückgabe verlangen. Leiten Sie aus der Bereitstellung einer Remote-Umgebung keine unbelegten Aussagen zu Sicherheit, Leistung oder Verfügbarkeit ab.

Vergleichen Sie Ihre aktuelle Lösung anhand konkreter Nachteile und Aufgaben. Ein allgemeines CI-System stellt möglicherweise nicht die erforderliche macOS-Werkzeugkette bereit. Ein selbst betriebener Mac verursacht eigenen Aufwand für Beschaffung, Wartung und Rechteverwaltung. Eine Auslagerung von API-Aufrufen deckt Build, Signatur und Stapling nicht automatisch ab. Wenn Sie für einen abgegrenzten Testlauf oder eine vorübergehende Mac-Aufgabe eine zusätzliche Umgebung erwägen, gleichen Sie Ihre Anforderungen mit den tatsächlich veröffentlichten Angaben zu VPSMAC-Mac-Knoten und Bestelloptionen ab. Für die Standortplanung können Sie zusätzlich die veröffentlichten Informationen zum VPSMAC-M4-Knoten in Hongkong prüfen.

Notieren Sie vor der Auswahl, welche Aufgaben zwingend Xcode, notarytool oder stapler benötigen und welche sich über die Notary API abbilden lassen. Wenn Sie kurzfristig Mac-Kapazität für einen Pilotlauf oder eine klar begrenzte Release-Aufgabe brauchen, können Sie die verfügbaren VPSMAC-Lieferangaben mit Ihrer Prüfliste vergleichen, statt Sicherheits- oder Kostenvorteile vorauszusetzen. Für dauerhaft hohe Last oder Anforderungen an lokale physische Schnittstellen kann ein eigener Mac die passendere Lösung sein.