notarytool-Notarisierung fehlgeschlagen: Checkliste 2026

„Notarisierung fehlgeschlagen“ beschreibt nicht immer denselben Fehler. Zwischen Upload, serverseitiger Prüfung, Ticket und lokaler Gatekeeper-Bewertung liegen mehrere getrennte Ebenen.

• Upload nicht abgeschlossen: Es wurde noch keine verwertbare Submission angelegt oder die Authentifizierung ist vor dem Upload abgebrochen.
• In Progress: Apple verarbeitet die Einsendung noch. Ein Log kann zu diesem Zeitpunkt noch nicht verfügbar sein.
• Invalid: Der Dienst hat das Archiv geprüft und mindestens ein kritisches Problem festgestellt.
• Accepted: Die Notarisierung wurde angenommen. Das bedeutet noch nicht, dass Ihr lokales Paket bereits ein angehängtes Ticket besitzt.
• Stapler-Fehler: Die Notarisierung war erfolgreich, aber das Ticket konnte nicht an App, DMG oder PKG angehängt werden.
• Gatekeeper-Ablehnung: Die lokale Sicherheitsbewertung schlägt fehl. Ursache können Signatur, Quarantäne, Paketstruktur oder ein fehlendes Ticket sein.

Apple stellt Status, Submission-ID und Log als getrennte Bestandteile des Workflows dar. Das Log enthält unter anderem Status, Zusammenfassung, Pfad, Schweregrad und konkrete Meldungen. Laden Sie es daher immer herunter, auch wenn der Status „Accepted“ lautet. Warnungen können den nächsten Release gefährden.

Verwenden Sie in Ihren Skripten ausschließlich Platzhalter für sensible Werte:

xcrun notarytool submit "/PFAD/ZUM/ARCHIV.zip" \
  --keychain-profile "KEYCHAIN_PROFIL" \
  --wait

Wenn der Befehl eine Submission-ID ausgibt, speichern Sie sie zusammen mit Commit, Build-Nummer und SHA-256-Prüfsumme des Archivs. Laden Sie danach das Log:

xcrun notarytool log "SUBMISSION-ID" \
  --keychain-profile "KEYCHAIN_PROFIL" \
  "/PFAD/ZUM/notary-log.json"

Bei einem noch laufenden Vorgang kann die Antwort sinngemäß melden, dass das Submission-Log noch nicht verfügbar ist. Das ist zunächst ein Statusproblem, kein Beweis für einen Fehler in Ihrer Signatur. Apple nennt keine feste Bearbeitungszeit. Planen Sie deshalb keine Pipeline, die nach einer beliebigen Wartezeit automatisch mehrfach neu einreicht.

Achtung: Eine neue Submission ohne neue Diagnose erzeugt nur weitere IDs. Die ursprüngliche Logdatei bleibt meist die wertvollste Spur, weil sie den geprüften Pfad und die konkrete Fehlerklasse enthält.

Für die Verteilung außerhalb des Mac App Store muss der Code mit einer passenden Developer-ID-Identität signiert sein. Entscheidend ist nicht nur die Signatur der äußersten .app. Frameworks, Plug-ins, XPC-Dienste, Hilfsprogramme und weitere Mach-O-Dateien innerhalb des Bundles müssen ebenfalls in einer gültigen Reihenfolge signiert worden sein.

Prüfen Sie zunächst, welche Identitäten der Schlüsselbund tatsächlich kennt:

security find-identity -v -p codesigning

Die Ausgabe sollte eine für Ihre Veröffentlichungsart passende Developer-ID-Identität enthalten. Eine sichtbare Zertifikatsbezeichnung allein beweist jedoch nicht, dass der zugehörige private Schlüssel vorhanden und verwendbar ist. In automatisierten Umgebungen treten häufig diese vier Fälle auf:

Verwenden Sie zur Detailprüfung:

codesign -dvv "/PFAD/ZUR/APP.app"

Suchen Sie nach einem Timestamp-Eintrag. Bei einer manuellen Signatur kann die Option beispielsweise so aussehen:

codesign --timestamp \
  --sign "DEVELOPER-ID-IDENTITÄT" \
  "/PFAD/ZUM/OBJEKT"

Verwenden Sie den tatsächlichen Namen Ihrer Identität nur lokal. In Dokumentation, Tickets und CI-Logs gehören Team-ID, Zertifikatsname, Key-ID und private Pfade grundsätzlich in geschützte Variablen oder anonymisierte Ausgaben. Apple erklärt die Anforderungen an Developer ID, sicheren Zeitstempel und Signaturprüfung in der Dokumentation zu häufigen Notarisierungsproblemen.

Eine nicht vollständige Zertifikatskette ist von einer abgelaufenen oder widerrufenen Identität zu unterscheiden. Prüfen Sie deshalb nicht nur den Namen des Zertifikats, sondern auch den privaten Schlüssel, die Schlüsselbundzugriffsrechte und die tatsächlich verwendete Signaturidentität. Ob Apple eine Submission akzeptiert, lässt sich nicht aus der bloßen Gültigkeitsanzeige eines Zertifikats ableiten.

Eine aktivierte Hardened Runtime ist für die Notarisierung kein abschließendes Qualitätssiegel, sondern eine Grundvoraussetzung mit zusätzlichen Laufzeitregeln. Sie schränkt unter anderem Code-Injection, unsichere Bibliotheksladung und bestimmte Formen dynamisch erzeugten Codes ein. Ausnahmen müssen genau zu den Funktionen Ihrer App passen. Die technischen Grenzen beschreibt Apple in der Dokumentation zur Hardened Runtime.

Prüfen Sie die tatsächlich signierten Entitlements, nicht nur die Xcode-Projekteinstellung:

codesign -d --entitlements :- "/PFAD/ZUR/APP.app"

Achten Sie besonders auf drei Fehlergruppen:

1. Falsches Format: Die Entitlements-Datei ist kein korrektes XML oder enthält Werte in einer Form, die der Signaturprozess nicht akzeptiert.
2. Unnötige Ausnahme: Ihre App fordert beispielsweise JIT- oder unsignierten ausführbaren Speicher an, obwohl die Funktion nicht benötigt wird.
3. Nachträgliche Änderung: Die App wurde signiert, danach wurden Entitlements, ausführbare Dateien oder eingebettete Komponenten ersetzt.

Das Entitlement com.apple.security.get-task-allow gehört nicht in eine reguläre Release-Version. Xcode verwendet es für Debug-Szenarien; bei einem eigenen Exportprozess wird es jedoch leicht versehentlich übernommen. Apple nennt dieses Entitlement ausdrücklich als häufige Ursache für eine abgelehnte Notarisierung.

Bei JIT, dynamischen Bibliotheken, Plug-ins oder eingebetteten Skript-Engines dürfen Sie nicht einfach alle Ausnahmen aktivieren. Prüfen Sie zuerst, welcher Prozess die Fähigkeit wirklich benötigt. Entitlements werden für ausführbaren Code gesetzt; Plug-ins erben die Laufzeitbedingungen ihres Host-Prozesses. Eine Ausnahme am falschen Ziel kann deshalb entweder wirkungslos sein oder die Sicherheitsprüfung unnötig erweitern.

Achten Sie außerdem darauf, dass die Entitlements der Haupt-App nicht automatisch für jede verschachtelte Komponente geeignet sind. Ein XPC Service, ein Hilfsprogramm und ein Framework können unterschiedliche Laufzeitaufgaben besitzen. Erstellen Sie daher für jedes signierte Ziel eine eigene Prüfausgabe.

Eine häufige Fehlannahme lautet: codesign auf der äußersten App sei ausreichend. Das ist bei komplexen macOS-Produkten falsch. Die äußere Signatur enthält Informationen über verschachtelten Code. Wird ein Framework, Plug-in, XPC Service oder Hilfsprogramm nachträglich ersetzt, kann die äußere Signatur ungültig werden.

Prüfen Sie die App und die enthaltenen Komponenten getrennt:

codesign --verify --deep --strict --verbose=2 \
  "/PFAD/ZUR/APP.app"

codesign -dvvv \
  "/PFAD/ZUR/APP.app/Contents/Frameworks/FRAMEWORK.framework"

codesign -dvvv \
  "/PFAD/ZUR/APP.app/Contents/XPCServices/DIENST.xpc"

--deep ist ein Prüfwerkzeug. Es ersetzt keine kontrollierte Signierreihenfolge. Signieren Sie von innen nach außen:

1. Drittanbieter-Binärdateien und Kommandozeilenwerkzeuge prüfen.
2. Frameworks und Plug-ins signieren.
3. XPC-Dienste und Hilfsprogramme signieren.
4. Die Haupt-App zuletzt signieren.
5. Erst danach DMG, PKG oder ZIP erzeugen.

Apple beschreibt verschachtelten Code als Bestandteil der Signaturstruktur. Bundles sollten nach dem Signieren wie schreibgeschützt behandelt werden. Ein Update-Mechanismus, der eine signierte Komponente austauscht, muss deshalb selbst Teil Ihres Signier- und Prüfprozesses sein. Weitere Details enthält Apples Code-Signing-Leitfaden.

Das Notarisierungslog ist hier besonders nützlich, weil es nicht nur „Invalid“ meldet, sondern häufig den fehlerhaften Pfad nennt. Prüfen Sie zuerst diesen Pfad. Arbeiten Sie sich dann eine Ebene nach außen vor. So vermeiden Sie, die Haupt-App neu zu signieren, obwohl tatsächlich ein einzelnes eingebettetes Werkzeug betroffen ist.

Die Fehlerklassen überschneiden sich, der letzte Prüfpunkt ist jedoch unterschiedlich. Ein ZIP kann zur Notarisierung eingereicht werden, aber nicht direkt mit stapler bearbeitet werden. Bei einem ZIP müssen Sie den enthaltenen Code stapeln und anschließend ein neues ZIP erzeugen. Apps, Disk Images und flache Installer-Pakete können dagegen jeweils eigene Ticket- und Validierungsschritte haben.

Ein sinnvoller Beleg für die lokale Prüfung ist:

spctl --assess --type execute --verbose=4 \
  "/PFAD/ZUR/APP.app"

spctl --assess --type install --verbose=4 \
  "/PFAD/ZUM/INSTALLER.pkg"

spctl bewertet das konkrete Objekt anhand seines Typs. Verwenden Sie deshalb bei einer App nicht den Installationsmodus und bei einem PKG nicht nur den Ausführungsmodus. Die Prüfung einer Arbeitskopie ist zudem nicht ausreichend, wenn Nutzer später ein anderes DMG oder ZIP herunterladen.

Bei einem DMG müssen Sie insbesondere kontrollieren, ob die enthaltene App nach dem Erstellen des Disk Images unverändert geblieben ist. Bei einem PKG prüfen Sie sowohl den Installer als auch die installierte App. Beim ZIP müssen Sie nach dem Stapeln ein neues Archiv erzeugen und genau dieses Archiv hashen, signieren oder veröffentlichen.

Ein Fehler beim API-Key, beim Keychain-Profil oder bei der Netzwerkverbindung bedeutet nicht automatisch, dass Apple Ihren Code abgelehnt hat. Trennen Sie diese Fälle in Ihren Logs:

• Credential-Fehler: Das Keychain-Profil ist nicht vorhanden, falsch benannt oder kann den privaten Schlüssel nicht verwenden.
• Upload-Fehler: Die Datei konnte nicht vollständig übertragen werden.
• Statusfehler: Der Upload war erfolgreich, aber die Verarbeitung ist noch nicht abgeschlossen.
• Logfehler: Die Submission-ID ist unbekannt oder das Log ist noch nicht verfügbar.
• Staplerfehler: Die Notarisierung ist angenommen, aber das lokale Artefakt kann kein Ticket erhalten.
• Gatekeeperfehler: Die lokale Prüfung des endgültigen Downloads schlägt fehl.

Für eine automatisierte Umgebung empfiehlt sich ein gespeichertes Keychain-Profil, statt ein Passwort in der Shell-Historie zu verwenden:

xcrun notarytool store-credentials "KEYCHAIN_PROFIL" \
  --apple-id "APPLE-ID-PLATZHALTER" \
  --team-id "TEAM-ID-PLATZHALTER" \
  --password "APP-SPECIFIC-PASSWORD-PLATZHALTER"

Die Werte sind Platzhalter. Übergeben Sie echte Zugangsdaten nicht in Tickets, Pull Requests oder frei lesbaren CI-Logs. Auf einem gemeinsam verwalteten Remote Mac muss der Schlüsselbund für den richtigen Benutzer verfügbar sein, beim nicht interaktiven Zugriff entsperrt werden können und durch Dateirechte sowie Zugriffskontrollen geschützt sein.

Wenn Sie API-Schlüssel verwenden, behandeln Sie die private Schlüsseldatei wie ein Produktionsgeheimnis. Speichern Sie sie nicht im Projektarchiv und schreiben Sie sie nicht in ein temporäres Verzeichnis mit globalen Leserechten. Der Release-Benutzer sollte nur auf die notwendigen Schlüsselbundobjekte und Credential-Profile zugreifen können. Nach einem Maschinenwechsel müssen Sie den gesamten Ablauf kontrolliert testen, statt lediglich die Zertifikatsdatei zu importieren.

Nach einer angenommenen Submission:

xcrun stapler staple "/PFAD/ZUR/APP.app"
xcrun stapler validate "/PFAD/ZUR/APP.app"

Für ein DMG oder PKG verwenden Sie den jeweiligen finalen Pfad. Bei einem ZIP arbeiten Sie mit der enthaltenen App und packen danach neu. Wenn stapler fehlschlägt, prüfen Sie zuerst den Objekttyp, die Netzwerkverbindung und ob das Ticket für genau dieses Artefakt ausgestellt wurde. Schließen Sie nicht direkt auf eine fehlerhafte Developer-ID-Signatur.

Erfahrung aus der Fehlersuche: Der Satz „Apple hat Accepted zurückgegeben“ beantwortet nur die serverseitige Notarisierungsfrage. Erst stapler validate, codesign, spctl und ein Test des tatsächlich heruntergeladenen Pakets zeigen, ob Ihr Veröffentlichungsartefakt vollständig ist.

Verwenden Sie diese Bedingungen, bevor Sie eine neue Submission starten:

• Wenn keine Submission-ID existiert, dann zuerst Authentifizierung, Xcode-Auswahl und Upload prüfen. Sonst mit dem vorhandenen Log weiterarbeiten.
• Wenn der Status „In Progress“ lautet und kein Log verfügbar ist, dann nicht blind neu signieren. Status und Submission-ID protokollieren und die Dienstverbindung prüfen.
• Wenn der Status „Invalid“ lautet und das Log einen konkreten Pfad nennt, dann genau dieses Objekt reparieren und anschließend die Signierkette von innen nach außen wiederholen.
• Wenn codesign scheitert, dann nicht mit stapler oder Gatekeeper weitermachen. Die Signatur ist die frühere Fehlerstufe.
• Wenn codesign erfolgreich ist, aber spctl ablehnt, dann das endgültige, gegebenenfalls quarantänisierte Distributionsartefakt testen.
• Wenn Accepted vorliegt, aber stapler validate scheitert, dann Paketformat, Zielpfad und Ticket-Anwendung prüfen.
• Wenn lokale Credentials nicht reproduzierbar verfügbar sind, dann den Release-Prozess nicht auf dieser Maschine belassen. Keychain-Profil, private Schlüssel und Toolchain müssen auf einer stabilen Umgebung wiederholbar bereitstehen.
• Wenn die App JIT, Plug-ins oder dynamische Bibliotheken benötigt, dann jede Runtime-Ausnahme einzeln begründen. Andernfalls auf die unnötige Ausnahme verzichten.

Diese Verzweigung verhindert, dass Sie einen Gatekeeper-Fehler mit einer neuen Developer-ID oder einen Credential-Fehler mit einer Änderung an den Entitlements behandeln.

1. Das finale Artefakt unverändert einfrieren

Erzeugen Sie zuerst genau die Datei, die Sie verteilen möchten. Berechnen Sie eine Prüfsumme und speichern Sie Commit, Build-Nummer, Xcode-Auswahl und Erstellungszeit. Nach der Signatur darf kein Skript mehr Dateien im Bundle austauschen.

Wenn Sie mehrere Formate aus demselben Build erstellen, definieren Sie eine klare Reihenfolge. Signieren Sie die App vollständig, erstellen Sie danach DMG, PKG oder ZIP und prüfen Sie anschließend jedes finale Artefakt. Vermeiden Sie es, eine App nach der Erstellung des Distributionspakets erneut zu verändern.

2. Die Toolchain festhalten

Prüfen Sie, welche Xcode-Installation xcrun verwendet:

xcode-select --print-path
xcrun --find notarytool
xcrun notarytool --help

Apple beschreibt die Migration zu notarytool und die Bedeutung der aktiven Xcode-Auswahl in der offiziellen Migrationsdokumentation. Mehrere Xcode-Versionen können über xcode-select oder DEVELOPER_DIR zu unterschiedlichen Werkzeugen führen. Die verwendete Toolchain gehört daher in das Build-Log.

3. Signatur und Entitlements prüfen

Führen Sie codesign --verify --deep --strict, die Entitlements-Ausgabe und die Prüfung des sicheren Zeitstempels aus. Speichern Sie die Ergebnisse als Artefakte. Entfernen Sie Team-ID, Benutzernamen und lokale Pfade aus öffentlich zugänglichen Logs.

Ergänzen Sie eine Prüfung, die den erwarteten Signieridentitätsnamen mit der tatsächlich verwendeten Identität vergleicht. So erkennen Sie früh, wenn ein Skript auf eine Entwicklungsidentität oder ein altes Zertifikat zurückgefallen ist.

4. Submission und Log auswerten

Übergeben Sie nur das finale Archiv. Speichern Sie Submission-ID und Status. Bei „Invalid“ laden Sie das JSON-Log herunter und sortieren Sie die Issues nach severity und path. Beginnen Sie mit dem ersten kritischen Fehler, nicht mit Warnungen ohne Bezug zum Abbruch.

Behandeln Sie ein leeres oder noch nicht verfügbares Log nicht als „keine Fehler“. Prüfen Sie, ob die Submission tatsächlich abgeschlossen ist und ob Ihr Credential-Profil dieselbe Apple-Entwicklerzuordnung verwendet wie beim Upload.

5. Ticket und Gatekeeper am Download testen

Stapeln und validieren Sie das passende Objekt. Erzeugen Sie danach den tatsächlichen Download, aktivieren Sie den Quarantänepfad durch Übertragung aus einer externen Quelle und testen Sie die Installation. spctl ist ein wichtiger automatisierter Check, ersetzt aber nicht den Test des realen Verteilungswegs.

Prüfen Sie abschließend, ob das veröffentlichte Objekt dieselbe Prüfsumme besitzt wie das getestete Artefakt. Ein CDN-Upload, ein nachträgliches Archivieren oder ein automatisches Umbenennen darf nicht unbemerkt ein anderes Objekt in den Downloadpfad bringen.

Eine einmalige Reparatur auf Ihrem lokalen Mac ist nicht automatisch ein stabiler Release-Prozess. Wenn die Veröffentlichung regelmäßig erfolgt, benötigen Sie eine Umgebung, in der dieselben Bedingungen reproduzierbar vorhanden sind:

• passende Xcode- und Command-Line-Tools-Auswahl,
• Developer-ID-Zertifikat mit privatem Schlüssel,
• geschützter und für den Build-Benutzer nutzbarer Keychain,
• gespeichertes notarytool-Credential-Profil,
• reproduzierbare Signierreihenfolge,
• Zugriff auf Zeitstempel- und Notarisierungsdienste,
• Aufbewahrung von Submission-ID und anonymisiertem JSON-Log,
• abschließende stapler- und Gatekeeper-Prüfung.

Datenschutz und Zugriffstrennung sind dabei genauso wichtig wie die Build-Leistung. Ein Remote Mac sollte nicht mit einem gemeinsam verwendeten Administratorkonto betrieben werden, wenn mehrere Personen Zugriff auf Signieridentitäten haben. Prüfen Sie, wer Keychain-Einträge lesen, Release-Skripte ändern und Logs exportieren darf. Speichern Sie keine vollständigen Credential-Dateien in allgemein zugänglichen Arbeitsverzeichnissen.

Dokumentieren Sie nicht nur „Build erfolgreich“. Ihre Abnahmekarte sollte für jeden Release diese Felder enthalten:

Wenn Ihr lokaler Mac nicht dauerhaft verfügbar ist, können Sie eine Remote-Mac-Umgebung für macOS-Builds als separate Veröffentlichungsmaschine evaluieren. Prüfen Sie dabei nicht nur die Rechenleistung. Entscheidend sind dauerhafte Keychain-Nutzung, Zugriffsschutz, Neustartverhalten, Xcode-Persistenz und die Möglichkeit, Logs sicher abzulegen. Für die Auswahl können Sie die CALMVPS-Preise und Mietzeiträume mit Ihren Release-Intervallen vergleichen.

Ein lokaler Mac ist weiterhin sinnvoll, wenn Sie täglich interaktiv entwickeln, physische Geräte anschließen oder langfristig eine feste Maschine mit voller Kontrolle benötigen. Ein Remote Mac passt eher, wenn Ihre Build- und Notarisierungsumgebung wiederholt, zeitweise oder unabhängig von Ihrem Arbeitsplatz laufen soll.

Bei einer fehlgeschlagenen notarytool-Notarisierung führt der schnellste Weg selten über einen erneuten Upload. Sichern Sie Status und Log, isolieren Sie die Fehlerstufe und prüfen Sie danach Signatur, Hardened Runtime, Entitlements, verschachtelten Code, Paketformat, Credentials, Ticket und Gatekeeper in genau dieser Beweiskette.

Wenn Ihr aktueller Mac nur sporadisch verfügbar ist, die Keychain nach Neustarts gesperrt bleibt oder Ihre Release-Skripte auf mehreren Rechnern unterschiedliche Xcode-Versionen verwenden, entstehen drei reale Schwachstellen: nicht reproduzierbare Signaturen, verlorene Submission-Logs und unvollständig getestete Distributionspakete. Ein eigener Mac kann diese Probleme lösen, bindet Sie aber an Anschaffung, Wartung, Stromversorgung und einen dauerhaft erreichbaren Standort. Eine gewöhnliche Cloud-Instanz ohne echten macOS-Zugriff scheidet für Xcode, Developer ID und notarytool ebenfalls aus.

In diesem Fall ist eine dauerhaft erreichbare Mac-Umgebung nicht automatisch billiger, aber für wiederkehrende Veröffentlichungen oft kontrollierbarer. Mieten Sie einen Mac von CALMVPS daher nur dann, wenn Sie die Umgebung anhand der oben genannten Abnahmekarte prüfen können und tatsächlich temporäre oder kontinuierliche macOS-Buildkapazität benötigen. Entscheidend ist nicht die Werbeaussage zur Hardware, sondern ob Zertifikat, Keychain, Toolchain, Submission-Log, Ticket und Gatekeeper-Test nach einem Neustart reproduzierbar funktionieren.