2026 Headless-Notarisierung auf Remote-Mac: notarytool mit App Store Connect API vs. Schlüsselbund-Profil + stapler, notarytool log und SSH-Entscheidungstabellen & FAQ
Aus „läuft auf meinem Mac mit GUI“ wird eine nachvollziehbare Pipeline: zuerst das richtige Auth-Modell für notarytool, dann die Fehlersuche zwischen stapler und notarytool log. Der Artikel richtet sich an SSH-gesteuerte Remote-Macs und CI-Runner — mit Vergleichstabellen und symptomorientierten Matrizen zum Einfügen ins Runbook.
1. Warum 2026 standardmäßig notarytool?
Apple hat Entwickler vom veralteten altool auf notarytool (in Xcode und den Command Line Tools) verlagert. Auf einem headless Remote-Mac zahlt sich das aus: eine CLI für Submit, Verlauf und detaillierte Logs — skriptfähig und runbook-tauglich — statt brüchiger Upload-Pfade oder manueller Klicks im Web.
Drei Schritte im Kopf behalten: Artefakt signieren → notarytool submit (Submission-ID festhalten) → auf Erfolg warten → (optional) stapler staple, um das Ticket auf der Festplatte zu verankern. Wo die Zugangsdaten liegen, entscheidet, ob diese Schleife unter SSH stabil bleibt.
2. Zwei Auth-Pfade: App Store Connect API-Schlüssel vs. Schlüsselbund-Profil
2.1 App Store Connect API (Issuer-ID + Key-ID + .p8)
Unter App Store Connect → Benutzer und Zugriff → Schlüssel einen API-Schlüssel anlegen und die .p8 herunterladen (nur einmal möglich). notarytool nutzt sie über --key, --key-id und --issuer. Typische Vorteile:
- Non-interaktiv: kein Apple-ID-Passwort und kein SMS-/Geräte-2FA — CI-tauglich.
- Rotation und Widerruf: klarer Schlüssel-Lebenszyklus und kleinere Schadensradius bei Leaks.
- Rechte nach Rolle: sauber auditierbare Grenzen.
Betrieblich die .p8 mit restriktiven Rechten (z. B. Modus 600) ablegen oder aus einem Secret-Manager injizieren — niemals ins Git. Dieselbe Schichtlogik gilt, wenn Sie mehrere Geheimnisse automatisieren: Secrets vom Build-Skript trennen, Rotation dokumentieren und Zugriff pro Unix-Benutzer auf dem Runner begrenzen.
2.2 Schlüsselbund-Profil (notarytool store-credentials)
notarytool store-credentials kann Apple-ID- oder API-Material als benanntes Profil im Login-Schlüsselbund speichern; anschließend rufen Sie --keychain-profile "Name" auf. Das passt zu einmaligem interaktivem Setup, das unter derselben Benutzersitzung wiederverwendet wird.
Auf headless Remote-Hosts achten Sie auf Diskrepanzen, wenn SSH-Non-Login-Shells, Daemons oder parallele Jobs beim Entsperren des Schlüsselbunds oder beim Besitzer des Login-Schlüsselbunds auseinanderlaufen — klassisch: „manuell grün, Pipeline flackert“. Exponieren Sie Verwaltungszugriff und Build-Geheimnisse möglichst auf getrennten Netz- und Identitätspfaden.
3. Entscheidungstabelle (ins Runbook kopieren)
| Dimension | ASC-API-Schlüssel (.p8) | Schlüsselbund-Profil |
|---|---|---|
| Headless / CI-Tauglichkeit | Hoch: Flags oder Umgebungsinjektion | Mittel: abhängig von Entsperren + Benutzerkontext |
| Credential-Rotation | Schlüssel tauschen, Pipeline-Variablen aktualisieren | Schlüsselbund-Eintrag oder Profil neu anlegen |
| Parallele Jobs | Geteilte .p8 pro Job (Rechte/Locking beachten) | ACLs und Sitzungskonflikte sind häufig |
| Compliance / Audit | Key-IDs und Ausstellungsnachweis sind explizit | Mehr Buchführung: welcher Host, welcher User |
| Typischer Einsatz | Geteilte Runner, gemietete Mac-Knoten, viele Repos | Solo-Dev-Maschinen mit stabiler Login-Sitzung |
Kernaussage: Für teamweite Remote-Mac-Notarisierung 2026 standardmäßig ASC-API + .p8; Profil-Flows nur, wenn derselbe macOS-Benutzer und zuverlässiges Schlüsselbund-Entsperren garantiert sind.
4. stapler vs. notarytool log: Triage über SSH
Sie beantworten unterschiedliche Fragen: stapler klärt, ob das Bundle auf der Platte ein Ticket trägt und für Gatekeeper stimmig wirkt; notarytool log <submission-id> liefert Apples serverseitiges Urteil inkl. strukturierter Fehlergründe.
| Symptom (häufig über SSH) | Erste Aktion | Warum |
|---|---|---|
notarytool submit meldet Invalid / Rejected |
notarytool log <id> ziehen (oder History für die ID) |
Ursache steckt in den Server-Scan-Ergebnissen; stapler zeigt das nicht |
| Status Accepted, Downloads melden trotzdem „nicht notarisiert“ | stapler staple auf dem ausgelieferten Artefakt, dann stapler validate |
Ticket fehlt in DMG/ZIP/nested App, oder es wurde eine unstapled Kopie ausgeliefert |
| Schneller Check: „Hat diese Datei auf der Platte ein Ticket?“ | stapler validate / checks im Stil von spctl |
Kein API-Roundtrip; gut für schnelles Preflight |
| Dasselbe Skript mal grün, mal rot | Submission-IDs pinnen und Logs diffen; dann Schlüsselbund, Parallelität, Proxies prüfen | Flakes hängen oft an Credential-Kontext oder Upload-Integrität; Logs trennen wiederholbare Ursache von Umgebungsdrift |
5. FAQ: typische Headless-Fallen
F1: CI meldet keinen Schlüsselbund-Zugriff oder fehlendes Profil?
Zuerst prüfen: Der Job-User weicht von dem ab, unter dem store-credentials lief, oder der Login-Schlüsselbund ist gesperrt. Dann: auf ASC-API-Tripel wechseln; wenn Profil bleiben muss, Runner unter launchd mit explizitem Entsperren fahren und Signier-/Notarisierungs-Phasen serialisieren.
F2: Accepted, aber stapler-Fehler?
Zuerst prüfen: falsches Staple-Ziel (z. B. App staplen, bevor das DMG neu gepackt wird) oder schreibgeschützter Pfad / Sandbox-Grenzen. Dann: an Apples unterstützte Staple-Formate anbinden und sicherstellen, dass die Pipeline dieselbe validierte Pfadinstanz anfasst.
F3: Log erwähnt Signatur, Hardened Runtime oder Entitlements?
Zuerst prüfen: Signatur vor der Notarisierung und deklarierte Entitlements widersprechen sich (inkl. eingebetteter Helfer). Dann: auf demselben Remote-Mac reproduzieren, codesign -dvvv und Entitlements vergleichen, fixen, erneut einreichen — vermeiden Sie „lokal gefixt, CI fährt noch das alte Skript“.
F4: Firmenproxy bricht Uploads?
Zuerst prüfen: Proxy blockiert oder MITM auf Apple-Upload-Endpunkte. Dann: Allowlist oder Bypass für den Builder; per SSH einen kleinen Test-Submit fahren, um TLS zu verifizieren, bevor große Artefakte folgen.
Die gesamte Kette von Archiv über Signatur bis Notarisierung lässt sich eng an iOS-CI auf einem Remote-Mac-mini 2026: Von Xcode bis TestFlight anbinden; für reine Fernzugriffs- und Shell-Entscheidungen ergänzt Remote-Mac-Workflows 2026: SSH vs. macOS Bildschirmfreigabe (VNC) die Betriebssicht.
Warum diese Pipeline auf einem Mac mini?
notarytool, codesign und stapler sind erstklassige macOS-Werkzeuge; auf einem Apple-Silicon Mac mini erhalten Sie dieselbe Laufzeit- und Sicherheitsbasis, die Apple bei der Notarisierung erwartet — ohne Sonderfälle auf fremden OS nachzubauen. Unified Memory und Leerlaufstrom oft nur im einstelligen Watt-Bereich eignen sich für dauerhaft erreichbare Remote-Builder: leise, kühl, günstig im Leerstand.
Für Teams machen Gatekeeper, SIP, FileVault und Dateirechte-Modelle leichter festzuhalten, wer von welchem Host submittet — genau die Compliance-Geschichte, die sich auf generischen VMs schwer faken lässt. Wenn Sie Archiv → Signatur → Notarisierung End-to-End verdrahten wollen, ist ein dedizierter Mac mini M4 oft der kosteneffizienteste Hardware-Anker — bei SSHMac Tarife prüfen und den passenden Fern-Mac für grüne Builds wählen.