Xcode 27: Privates Swift Package lässt sich nicht laden? Fehlerbehebung 2026

Die Apple-Anleitung für Swift-Package-CI ordnet SSH-Zugangsdaten dem macOS-Benutzer zu, der den CI-Auftrag tatsächlich ausführt, und verlangt eine passende known_hosts-Konfiguration. Für diese Woche empfehlen wir deshalb diese Reihenfolge: zuerst das Ausführungskonto und dessen SSH-Zugang prüfen, dann known_hosts, anschließend Package.resolved und erst zuletzt Git- beziehungsweise Xcode-Konfigurationen. Schalten Sie die Host-Prüfung nicht vorschnell aus und löschen Sie nicht als ersten Schritt den Paket-Cache.

Geeignet für: Entwicklerinnen und Entwickler, die ein Projekt mit Xcode 27 auf einem Remote Mac bauen und private Swift Packages verwenden.
DevOps-Verantwortliche, die SSH-Zugänge für CI-Konten mit minimalen Rechten verwalten.
Mobile-Teams, die einen lokalen Build auf eine entfernte macOS-Umgebung umstellen und Versionsabweichungen einordnen möchten.

„Das Paket lässt sich nicht laden“ beschreibt noch keine Ursache. Ein fehlendes oder falsches SSH-Schlüsselpaar ist ein Authentifizierungsproblem; eine Ablehnung des Server-Fingerprints ist ein Problem der Host-Prüfung. Ein anderer aufgelöster Paketstand weist dagegen auf die Versionsauflösung oder auf abweichende Paketadressen hin. Diese Fälle benötigen unterschiedliche Korrekturen.

Führen Sie deshalb denselben Commit mit derselben Scheme- und Build-Konfiguration lokal und in CI aus. Vergleichen Sie nicht nur die letzte Fehlermeldung, sondern den frühesten Fehler im Ablauf: Wird das Repository gar nicht erreicht, wird die Verbindung wegen des Hosts abgewiesen oder schlägt erst die Auflösung einer Version fehl? Notieren Sie außerdem den tatsächlichen macOS-Benutzer des CI-Prozesses. Ein erfolgreicher Zugriff aus Ihrer interaktiven Administratorsitzung beweist nicht, dass der Runner dieselben Zugangsdaten sieht.

Bei Xcode 27 sollten Sie die auf dem konkreten Knoten installierte Version und die macOS-Kompatibilität gesondert erfassen. Der Versionsstatus und die Systemanforderungen können sich ändern; maßgeblich sind die aktuellen Xcode-Systemanforderungen und die Xcode-27-Versionshinweise. Übertragen Sie daher keine Annahme über einen Knoten ungeprüft auf alle CI-Systeme.

Die Tabelle dient der ersten Einordnung, nicht als Beweis: Ein CI-Auftrag kann mehr als eine Abweichung aufweisen. Ändern Sie möglichst nur eine Schicht gleichzeitig, damit ein erfolgreicher Wiederholungslauf auch eine nachvollziehbare Ursache hat.

Die entscheidende Frage lautet nicht, ob auf dem Mac ein Schlüssel existiert, sondern ob der Benutzer, unter dem der Runner den Build startet, ihn verwenden darf. Ein Schlüssel im Home-Verzeichnis eines Administrators steht einem separaten Runner-Konto nicht automatisch zur Verfügung. Dasselbe gilt für SSH-Agent-Variablen und benutzerspezifische Konfigurationsdateien.

Fügen Sie für einen kontrollierten Test vorübergehend nicht geheime Diagnosebefehle in denselben CI-Schritt ein, der später xcodebuild startet:

id -un
printf 'HOME=%s\n' "$HOME"
printf 'SSH_AUTH_SOCK=%s\n' "${SSH_AUTH_SOCK:-nicht gesetzt}"
ls -ld "$HOME" "$HOME/.ssh" 2>/dev/null || true

Diese Ausgabe zeigt die Prozessidentität und relevante Pfade, aber keine privaten Schlüssel. Vermeiden Sie Befehle wie env ohne Filter oder das Ausgeben von Schlüsseldateien: CI-Protokolle werden häufig gespeichert und können von mehr Personen eingesehen werden als die ursprüngliche Build-Sitzung.

Prüfen Sie danach den Zugriff mit genau dem Repository-Host und der URL, die das Projekt verwendet. Ein Test mit git ls-remote kann zeigen, ob der Prozess das Repository lesen darf:

git ls-remote 'ssh://git@code.example.invalid/team/private-package.git' HEAD

Ersetzen Sie die Beispieladresse durch die tatsächliche SSH-Adresse. Führen Sie den Test im CI-Schritt und nicht nur in einer angemeldeten Shell aus. Wenn der Zugriff scheitert, prüfen Sie zuerst, ob der Schlüssel dem Runner-Konto zugeordnet ist, ob der Schlüssel geladen wird und ob das Konto Leserechte auf genau dieses Repository besitzt.

Wie verwendet xcodebuild die SSH-Konfiguration des CI-Kontos?
Entscheidend ist die Umgebung des Prozesses, der xcodebuild startet. Lassen Sie den Runner den Build unter seinem regulären Ausführungskonto beginnen und prüfen Sie innerhalb desselben Auftrags HOME, SSH_AUTH_SOCK und die erreichbare Repository-URL. Ein Test in einer Administrator-Sitzung oder ein manuell gestarteter Agent kann ein anderes Ergebnis liefern und ist kein Ersatz für den CI-Test.

Für private Abhängigkeiten sollte ein Zugang mit möglichst begrenztem Umfang verwendet werden. Die Dokumentation zu schreibgeschützten Bereitstellungsschlüsseln erläutert, wie sich ein Repository-Zugang auf Lesezugriff beschränken lässt. Prüfen Sie die Rechte passend zu Ihrer Hosting-Umgebung; erweitern Sie Berechtigungen nicht pauschal für den gesamten Runner oder ein persönliches Entwicklerkonto.

Wenn Schlüssel über einen SSH-Agent bereitgestellt werden, dokumentiert Apples technische Notiz den Zusammenhang zwischen SSH-Agent und Anwendungen, die SSH verwenden. Sie ist eine nützliche Referenz, wenn ein Schlüssel in einer interaktiven Sitzung funktioniert, aber im CI-Prozess nicht angeboten wird: Apples technische Hinweise zum SSH-Agent. Geben Sie weder Agent-Sockets noch Schlüsselmaterial in allgemein lesbare Artefakte oder Protokolle aus.

Eine erfolgreiche Authentifizierung reicht nicht, wenn SSH dem Zielhost nicht vertraut. Die Datei known_hosts ist an den Benutzerkontext gebunden: Der CI-Prozess muss sie im eigenen Home-Verzeichnis lesen können. Eine korrekt gepflegte Datei im Home-Verzeichnis eines Administrators behebt den Fehler eines anderen Kontos nicht.

Lassen Sie im CI-Auftrag zunächst den effektiven SSH-Zielnamen und die ausgewählten Einstellungen anzeigen:

ssh -G git@code.example.invalid | grep -E '^(hostname|user|port|identityfile|stricthostkeychecking) '

ssh -G prüft die aufgelöste Konfiguration, ohne eine Anmeldung am Repository vorzunehmen. Vergleichen Sie insbesondere hostname, user und identityfile mit der tatsächlich in Package.resolved oder der Projektkonfiguration hinterlegten Adresse. SSH-Regeln mit Host-Mustern können für einen Alias gelten, aber nicht für den ausgeschriebenen Hostnamen, den der Paketmanager verwendet.

Erfassen Sie einen neuen Host-Schlüssel nicht blind mit einem automatischen Erstkontakt. Vergleichen Sie den Fingerprint mit einem vertrauenswürdigen, separat bezogenen Eintrag. Die offizielle Übersicht der SSH-Fingerprints beschreibt diese Prüfung für den dort dokumentierten Dienst; für andere Hosting-Systeme ist deren offizielle Fingerprint-Quelle maßgeblich. Die konkrete Vertrauensentscheidung muss also zur verwendeten Repository-Plattform passen.

Wenn SSH mit „Host key verification failed“ abbricht, behandeln Sie dies als Host-Prüfungsfehler und nicht als Beleg für einen falschen privaten Schlüssel. Die Dokumentation zur Meldung bei fehlgeschlagener Host-Schlüsselprüfung beschreibt die typische Bedeutung. Die SSH-Optionen und ihre Wirkung sind in der OpenBSD-Handbuchseite zu ssh_config festgehalten.

Setzen Sie StrictHostKeyChecking=no nicht als Standardkorrektur. Damit kann SSH eine falsche oder unerwartete Gegenstelle akzeptieren, statt den Fehler sichtbar zu machen. Falls ein zeitlich begrenzter Test in einer isolierten Umgebung ausnahmsweise nötig ist, dokumentieren Sie den Zweck, verwenden Sie keine produktiven Zugangsdaten und stellen Sie die ursprüngliche Host-Prüfung unmittelbar danach wieder her. Für den normalen Betrieb ist ein kontrolliert gepflegter known_hosts-Eintrag vorzuziehen.

Package.resolved beantwortet eine andere Frage als SSH: Die Datei hält die aufgelösten Abhängigkeitsversionen fest, erteilt aber keine Repository-Berechtigung. Ist die Anmeldung erfolgreich, kann eine falsche oder fehlende Sperrdatei dennoch zu unerwarteten Versionsständen führen. Umgekehrt repariert eine korrekt eingecheckte Sperrdatei keinen verweigerten SSH-Zugriff.

Prüfen Sie im Commit, der tatsächlich gebaut wird, ob die für das Projekt relevante Package.resolved enthalten ist. Vergleichen Sie den Dateiinhalt zwischen lokalem Checkout und CI-Arbeitsverzeichnis, und kontrollieren Sie, ob die private Abhängigkeit dort auf dieselbe Repository-Adresse verweist, die der CI-Benutzer erreichen kann. Eine HTTPS-Adresse und eine SSH-Adresse können unterschiedliche Anmeldewege auslösen, auch wenn sie auf dasselbe Projekt verweisen sollen.

Die Sperrdatei ist eingecheckt, aber CI löst eine andere Paketversion auf. Was ist zu prüfen?
Prüfen Sie zuerst, ob CI denselben Commit und dieselbe Sperrdatei verwendet, ob die Paket-URL übereinstimmt und ob der Build die automatische Neuauflösung unterbindet. Ändern Sie nicht zuerst die Abhängigkeit oder löschen Sie den Cache: Sonst lässt sich nach einem grünen Lauf nicht mehr unterscheiden, ob die Ursache die Sperre, der Zugriff oder ein neu aufgelöster Stand war.

Die Apple-Anleitung zum Bauen von Swift Packages in CI empfiehlt, Package.resolved einzureichen und beim direkten Aufruf von xcodebuild die automatische Paketauflösung zu deaktivieren, wenn der festgehaltene Stand verwendet werden soll. Übernehmen Sie die in der aktuellen Dokumentation beschriebene Option nur dann, wenn sie zu Ihrem Projekt und Build-Aufruf passt. Sichern Sie vor einer Änderung den bisherigen Aufruf und vergleichen Sie anschließend die protokollierten Paketversionen.

Auch wenn das Konto und die Host-Prüfung plausibel aussehen, kann der Build einen anderen Git-Pfad, eine URL-Umschreibung, einen Proxy oder eine spezielle SSH-Regel verwenden als Ihre lokale Shell. Vermeiden Sie die Annahme, dass jede Xcode-Version unter allen Umgebungen identisch auf die System-Git-Konfiguration zugreift. Prüfen Sie zunächst, was der betroffene Knoten tatsächlich verwendet.

Erfassen Sie mit dem CI-Konto die relevanten, nicht geheimen Einstellungen:

command -v git
git --version
git config --show-origin --get-regexp 'url\..*\.insteadof|core\.sshCommand|http\..*proxy' || true

Behandeln Sie die Ausgabe vertraulich, falls interne Repository-Pfade oder Proxy-Adressen sichtbar werden. Prüfen Sie außerdem, ob eine Umgebungsvariable wie GIT_SSH_COMMAND gesetzt ist und ob eine globale Git-Konfiguration die Paketadresse umschreibt. Das Verhalten der SSH-Client-Konfiguration lässt sich mit den zuvor genannten ssh -G-Ergebnissen ergänzen.

Testen Sie die Verwendung des System-Git nur dann als gezielte Hypothese, wenn die Protokolle auf einen abweichenden Git-Pfad oder eine konkrete Konfigurationsdifferenz hinweisen. Ändern Sie nicht gleichzeitig Runner-Umgebung, SSH-Regeln und Xcode-Aufruf. Halten Sie pro Versuch fest: Commit, ausführender Benutzer, Git-Version, Paket-URL, verwendete Build-Option und Ergebnis der Auflösung. So bleibt ein erfolgreicher Test reproduzierbar, statt lediglich einen kurzfristig grünen Build zu erzeugen.

Führen Sie den abschließenden Test mit demselben Commit und dem regulären CI-Ausführungskonto in einer sauberen Arbeitskopie aus. Lassen Sie zuerst die Abhängigkeiten mit den vorgesehenen Einstellungen auflösen und starten Sie anschließend den eigentlichen Build. Protokollieren Sie, an welcher Stufe ein Fehler auftritt, welche Paketversionen verwendet wurden und ob der Repository-Zugriff erfolgreich war. Maskieren Sie Geheimnisse, bevor Protokolle geteilt oder gespeichert werden.

Verwenden Sie für die Entscheidung diese Bedingungen:

• Wenn das Runner-Konto die SSH-Verbindung nicht authentifizieren kann, dann korrigieren Sie die Zuordnung des Schlüssels oder dessen eng begrenzte Leseberechtigung. Erweitern Sie nicht die Rechte des gesamten Knotens.
• Wenn die Authentifizierung funktioniert, aber die Host-Prüfung scheitert, dann verifizieren Sie den Fingerprint und pflegen Sie known_hosts für das CI-Konto. Schalten Sie die Prüfung nicht dauerhaft ab.
• Wenn der Zugriff funktioniert, aber die Paketversion abweicht, dann prüfen Sie Commit, Package.resolved, Paketadresse und automatische Auflösung, bevor Sie Abhängigkeiten aktualisieren.
• Wenn nur ein abweichender Git- oder SSH-Aufruf den Fehler erklärt, dann ändern Sie ausschließlich diese belegte Konfiguration und bewahren Sie den Vorher-Nachher-Vergleich auf.
• Wenn mehrere Projekte auf einem gemeinsam genutzten Knoten Zugangsdaten oder Home-Verzeichnisse teilen müssten, dann verwenden Sie ein separates Ausführungskonto oder einen isolierten Build-Knoten, statt die gemeinsame Berechtigungsfläche zu vergrößern.

Wo sollen SSH-Schlüssel und known_hosts für ein privates Swift Package liegen?
Beides muss im Kontext des Kontos funktionieren, das den CI-Auftrag startet: Der Prozess braucht Zugriff auf den vorgesehenen Schlüssel beziehungsweise SSH-Agenten und auf die passende known_hosts-Datei. Eine Konfiguration ausschließlich für das Administratorkonto genügt nicht. Verifizieren Sie den Host-Fingerprint über eine vertrauenswürdige Quelle und geben Sie keine Schlüsseldatei im Build-Protokoll aus.

Das ist auch eine Kosten- und Betriebsentscheidung. Ein gemeinsamer Mac kann für mehrere nicht vertrauliche Builds effizient sein, wird aber problematisch, wenn Teams Zugangsdaten nicht sauber voneinander trennen oder Änderungen an globaler Git-Konfiguration unbeabsichtigt andere Projekte beeinflussen. Ein isoliertes Konto oder ein dedizierter Knoten verursacht Verwaltungsaufwand, kann aber Zugriffsrechte und Fehlerursachen klarer abgrenzen. Dokumentieren Sie die Entscheidung anhand von Repository-Rechten, Geheimnisverwaltung und Wiederholbarkeit, nicht allein anhand eines erfolgreichen Einzelbuilds.

Wenn der aktuelle Build-Knoten nur sporadisch verfügbar ist, Zugangsdaten zwischen Benutzerkonten kopiert werden oder lokale Administratorrechte als Ersatz für eine saubere CI-Identität dienen, sollten Sie zuerst den Betriebsweg korrigieren. Ein Mac mini im eigenen Bestand bietet direkte Kontrolle über Hardware und lokale Schnittstellen, bindet jedoch Kapital und erfordert eigene Wartung, Aktualisierung und Ausfallsicherung. Ein allgemeiner Linux-Server ersetzt die macOS-spezifische Build-Umgebung nicht, wenn der Auftrag Xcode benötigt.

Für zeitlich begrenzte Builds, Migrationstests oder einen reproduzierbaren isolierten CI-Knoten kann die Miete eines Remote Mac flexibler sein als der Kauf zusätzlicher Hardware. Sie sollten dennoch vorab klären, wie Ausführungskonto, SSH-Zugang, Geheimnisse, Protokollzugriff und Datenlöschung geregelt werden, und die Anforderungen Ihrer Organisation an Datenschutz und DSGVO berücksichtigen. Wenn Ihr Team eine kontrollierbare macOS-Umgebung benötigt, können Sie sich die Remote-Mac-Angebote von JEXCLOUD ansehen; für dauerhaft ausgelastete Workloads oder benötigte physische Schnittstellen kann ein eigener Mac die passendere Lösung bleiben.

Die nächste sinnvolle Maßnahme ist kein pauschaler Wechsel des Knotens, sondern ein sauberer Vergleich: gleicher Commit, tatsächliches Runner-Konto, geprüfter SSH-Host und festgehaltene Paketversionen. Wenn Ihr vorhandener Aufbau diese Bedingungen nicht verlässlich erfüllt und Sie zunächst einen isolierten macOS-CI-Knoten testen möchten, prüfen Sie die Mietoptionen für einen Remote Mac von JEXCLOUD anhand von Zugriffsmodell und Laufzeitbedarf.