Apple dokumentiert Package.resolved als Möglichkeit, die Abhängigkeitsversionen in CI-Builds festzuhalten (Leitfaden zu Swift-Paketen in CI). Symptom → schnellster Diagnoseweg: Wenn Xcode 27 private Swift-Pakete beim Remote-Build nicht abrufen kann, prüfen Sie zuerst die tatsächlich verwendete Repository-URL, den macOS-Ausführungsbenutzer und dessen Zugangsdaten. Verifizieren Sie danach die Lockdatei. Xcode Cloud und ein selbst gehosteter Remote Mac benötigen unterschiedliche Autorisierungswege; Zugangsdaten gehören weder in das Repository noch in eine URL.

Dieser Leitfaden ist für Sie, wenn ein lokaler Build gelingt, der Remote-Build aber beim Auflösen eines privaten Swift-Pakets scheitert. Er richtet sich außerdem an Entwickler, die xcodebuild-Aufträge oder selbst gehostete Runner verwalten und SSH-Zugriff nachvollziehbar absichern müssen. Auch kleine Teams, die private Abhängigkeiten mit Xcode Cloud verwenden, können damit den plattformspezifischen Autorisierungsweg von eigener Mac-Konfiguration unterscheiden.

Den Fehler zuerst der richtigen Phase zuordnen

Ein fehlgeschlagener Gesamtstatus sagt noch nicht, ob das Paket nicht erreichbar war, die Anmeldung abgelehnt wurde oder erst der Swift-Compiler einen Fehler gefunden hat. Suchen Sie im Build-Bericht oder im vollständigen xcodebuild-Protokoll nach dem ersten Fehler. Notieren Sie dazu, ob der Auftrag in Xcode Cloud, über einen Runner oder manuell auf einem Remote Mac gestartet wurde, welches Arbeitsverzeichnis verwendet wurde und welcher macOS-Benutzer den Prozess ausführt.

Ordnen Sie den Befund einer dieser Ursachen zu:

  • Netzwerk oder DNS: Der Host lässt sich nicht erreichen oder der Verbindungsaufbau wird vor einer Anmeldung abgebrochen. Prüfen Sie die Erreichbarkeit aus der Build-Umgebung, nicht nur von Ihrem Laptop.
  • Repository-Adresse oder Pfad: Der Server ist erreichbar, aber der angeforderte Pfad zeigt auf ein anderes oder nicht vorhandenes Repository. Gleichen Sie die URL mit der im Projekt hinterlegten Paketquelle ab.
  • Authentifizierung oder Berechtigung: Die Verbindung erreicht den Quellcode-Server, doch der angeforderte Zugriff wird abgelehnt. Prüfen Sie, welches Konto und welche Berechtigung für genau diesen Auftrag gelten.
  • Auflösung oder Lockdatei: Das Repository ist zugänglich, aber die erwartete Revision oder eine zulässige Versionskombination kann nicht aufgelöst werden. Vergleichen Sie die protokollierte Revision mit Package.resolved.
  • Swift-Kompilierung: Die Paketquellen wurden bezogen und die Auflösung war erfolgreich; der Fehler tritt erst beim Kompilieren auf. Dann sind Zugangsdaten nicht die erste Baustelle.
Die [Apple-Dokumentation zu häufigen Konfigurations- und Build-Problemen](https://developer.apple.com/documentation/xcode/resolving-common-configuration-and-build-issues?_7) behandelt die Abgrenzung von Konfigurations- und Build-Fehlern. Verwenden Sie sie als Orientierung, aber beurteilen Sie den konkreten Fehler anhand der ersten relevanten Meldung in Ihrem eigenen Build-Protokoll.

**Achtung:** Löschen Sie nicht vorsorglich alle Caches und starten Sie die Auflösung nicht blind neu. Dadurch kann sich der sichtbare Fehler ändern, ohne dass Repository-Zugriff, Berechtigungen oder eine fehlende Lockdatei behoben sind.

Messpunkt: Stimmen Paketquelle und erreichbares Repository überein?

Prüfen Sie zunächst, welche Adresse die fehlgeschlagene Aufgabe wirklich abruft. Swift-Paketabhängigkeiten können in der Paketbeschreibung deklariert sein; vergleichen Sie diese Quelle mit den Angaben im Projekt und dem aufgelösten Paketstatus. Apple beschreibt die verfügbaren Angaben für eine Swift-Paketabhängigkeit. Entscheidend ist nicht, welche URL Sie erwarten, sondern welche URL der Remote-Auftrag verwendet.

Gehen Sie die Prüfung getrennt durch:

  • Quelle finden: Suchen Sie in Package.swift, den Xcode-Projekteinstellungen und Package.resolved nach der betreffenden Abhängigkeit. Notieren Sie den Paketnamen und die Quelle, ohne interne Repository-Adressen in Tickets oder öffentliche Protokolle zu kopieren.
  • Adresse vergleichen: Stellen Sie fest, ob der Auftrag SSH oder HTTPS verwendet. Vergleichen Sie die tatsächliche Adresse mit der für den jeweiligen Build vorgesehenen Adresse. Eine URL-Änderung ist kein allgemeiner Fix für einen Authentifizierungsfehler.
  • Erreichbarkeit testen: Prüfen Sie aus der Umgebung des Auftrags, ob der Host erreichbar ist und der Repository-Pfad existiert. Scheitert bereits die Verbindung, beheben Sie zunächst DNS, Netzwerkregeln oder Pfadfehler.
  • Revision nachweisen: Prüfen Sie, ob der angeforderte Zweig oder Tag tatsächlich vorhanden und für das verwendete Konto sichtbar ist. Ein fehlender Verweis und ein verweigerter Zugriff sind unterschiedliche Befunde.
  • Build-Eingang dokumentieren: Halten Sie fest, ob der Fehler bei einem interaktiven Xcode-Build, einem CI-Auftrag oder einem direkten xcodebuild-Aufruf auftritt. Die Referenz zu Xcode-Kommandozeilenwerkzeugen hilft, die verwendeten Kommandozeilenoptionen einzuordnen.
Führen Sie einen Erreichbarkeitstest mit derselben URL und demselben Benutzer durch, die auch der eigentliche Auftrag verwendet. Ein erfolgreicher Test unter Ihrem persönlichen Konto beweist nicht, dass ein Hintergrunddienst auf dieselbe Quelle zugreifen kann.

Messpunkt: Welcher macOS-Benutzer stellt die Zugangsdaten bereit?

Auf einem selbst gehosteten Mac hängen SSH-Schlüssel, Git-Konfiguration, bekannte Hostschlüssel und ein laufender SSH-Agent am jeweiligen Benutzerkontext. Startet ein Runner unter einem Dienstkonto, kann er nicht automatisch auf die Einstellungen eines interaktiv angemeldeten Entwicklerkontos zugreifen. Ermitteln Sie daher den tatsächlichen Benutzer direkt im Build-Auftrag, statt ihn aus der Konfiguration der Verwaltungsoberfläche abzuleiten.

Prüfen Sie anschließend:

  • SSH-Schlüssel: Liegt der erforderliche Schlüssel im vorgesehenen Benutzerkontext, und kann der Auftrag ihn ohne interaktive Eingabe verwenden? Geben Sie den Schlüsselinhalt nicht aus.
  • SSH-Agent: Ist ein Agent für genau diese Sitzung erreichbar, wenn der Arbeitsablauf darauf angewiesen ist? Ein Agent, der nur in einem geöffneten Terminal läuft, ist kein verlässlicher Nachweis für einen späteren CI-Auftrag.
  • Hostschlüsselprüfung: Kann der Benutzer den Quellcode-Server anhand seiner vertrauenswürdigen Hostschlüssel verifizieren? Schalten Sie die Prüfung nicht ab, um einen Verbindungsfehler zu umgehen.
  • Git-Konfiguration: Prüfen Sie, ob die benötigte Konfiguration für den Ausführungsbenutzer gilt und ob Xcode beziehungsweise der Build tatsächlich das erwartete Git-Verhalten verwendet.
  • Berechtigungsumfang: Stellen Sie sicher, dass der Zugang nur die erforderlichen Repositories und Aktionen abdeckt. Ein umfassenderer Schlüssel behebt keine falsche URL und vergrößert zugleich die möglichen Folgen eines Abflusses.
Wenn Sie eine macOS-Git-Konfiguration statt des integrierten Verhaltens von Xcode benötigen, prüfen Sie die für Ihren Build passende Vorgehensweise anhand der Apple-Hinweise zu [Swift-Paketen in CI](https://developer.apple.com/documentation/xcode/building-swift-packages-or-apps-that-use-them-in-continuous-integration-workflows?v=1.1.1). Übernehmen Sie Konfigurationsschritte nicht ungeprüft zwischen unterschiedlichen Xcode-Versionen oder Ausführungsumgebungen.

Für Xcode Cloud gilt ein anderer Pfad: Autorisieren Sie den Zugriff über den von Apple vorgesehenen SCM-Ablauf, statt lokale Schlüsseldateien aus einem selbst gehosteten Mac nachzubilden. Apple beschreibt die Voraussetzungen unter Abhängigkeiten für Xcode Cloud und erläutert die Einrichtung der Quellcodeverwaltung für Xcode. Für die Verbindung mit einem unterstützten Repository-Dienst ist zusätzlich Apples Anleitung zum Verbinden von Xcode Cloud mit dem Quellcode-Repository maßgeblich. Überprüfen Sie die aktuellen Schritte in der verwendeten Oberfläche, statt die Anleitung für einen selbst gehosteten Mac auf Xcode Cloud zu übertragen.

Messpunkt: Ist Package.resolved am erwarteten Ort versioniert?

Eine Lockdatei trägt zur reproduzierbaren Paketauflösung bei, ersetzt aber keine Berechtigung. Wenn die CI-Umgebung das Repository nicht lesen darf, behebt ein eingechecktes Package.resolved den Zugriff nicht. Ist der Zugriff dagegen erfolgreich, kann eine fehlende oder nicht berücksichtigte Lockdatei dazu führen, dass sich die aufgelösten Revisionen von Ihrer lokalen Erwartung unterscheiden.

Prüfen Sie zuerst, welche Package.resolved-Datei für Ihr Projekt und den verwendeten Arbeitsablauf maßgeblich ist. Stellen Sie dann fest, ob sie im Versionskontrollsystem enthalten ist und ob der Remote-Auftrag dieselbe Version des Projektstands verwendet wie Ihre lokale Prüfung. Vergleichen Sie nicht nur Paketnamen: Entscheidend sind die aufgelösten Versionen beziehungsweise Revisionen.

Gehen Sie bei Abweichungen in dieser Reihenfolge vor:

  1. Bestätigen Sie, dass der Auftrag den erwarteten Commit des Projekts auscheckt.
  2. Prüfen Sie, ob die relevante Lockdatei in diesem Commit enthalten ist und am erwarteten Ort liegt.
  3. Vergleichen Sie die protokollierte Paketauflösung mit den festgehaltenen Revisionen.
  4. Wenn die Auflösung trotz erreichbarer Quelle abweicht, untersuchen Sie Versionsanforderungen und verfügbare Zweige oder Tags.
  5. Erst wenn diese Befunde übereinstimmen, führen Sie den vollständigen Build erneut aus.
Nutzen Sie eine erzwungene Neuauflösung nicht als pauschalen Reparaturversuch. Sie kann eine fehlende Lockdatei oder veraltete Paketauflösung sichtbar machen, ist aber kein Ersatz für einen Nachweis, dass die gewünschte Revision erreichbar und der Zugriff autorisiert ist. Apples [CI-Leitfaden zu festgeschriebenen Paketversionen](https://developer.apple.com/documentation/xcode/building-swift-packages-or-apps-that-use-them-in-continuous-integration-workflows?v=1.1.1) beschreibt die Rolle von Package.resolved im kontinuierlichen Build.

Messpunkt: Bleiben Zugangsdaten vertraulich und der Build reproduzierbar?

Bevor Sie einen Schlüssel austauschen oder eine Konfiguration ändern, prüfen Sie, ob Geheimnisse bereits offengelegt wurden. Suchen Sie in Repository-Dateien, Build-Skripten, URL-Feldern, Protokollausgaben und gespeicherten Build-Artefakten nach versehentlich ausgegebenen Zugangsdaten. Ein Schlüssel in einer URL oder einer protokollierten Kommandozeile bleibt möglicherweise sichtbar, auch wenn Sie die betreffende Datei später ändern.

Wenn Sie eine Offenlegung feststellen, behandeln Sie das Geheimnis als kompromittiert: entziehen oder ersetzen Sie es nach dem zuständigen Prozess, prüfen Sie den Zugriffsumfang und entfernen Sie gespeicherte Offenlegungen dort, wo Sie sie kontrollieren. Ändern Sie gemeinsam genutzte Git- oder Runner-Konfigurationen nicht ohne festzuhalten, welche weiteren Aufträge davon abhängen. Bei einer Bereinigung von Caches müssen Sie ebenfalls berücksichtigen, ob sie andere Builds beeinflusst oder lediglich eine reproduzierbare Prüfung erschwert.

Verifizieren Sie eine Reparatur mit einem sauberen Arbeitsverzeichnis und demselben Build-Eingang, der in der Produktion scheitert. Halten Sie drei getrennte Ergebnisse fest:

  • Zugriff: Die Aufgabe erreicht genau das erwartete private Repository mit dem vorgesehenen Benutzer.
  • Auflösung: Die ausgewählten Revisionen stimmen mit der erwarteten Lockdatei beziehungsweise den festgelegten Versionsanforderungen überein.
  • Build: Der Build läuft über die Paketauflösung hinaus und endet ohne den zuvor beobachteten Fehler.
Bewerten Sie den Prüfpfad qualitativ: **hoch belastbar** ist ein Nachweis aus demselben Konto, derselben Build-Umgebung und derselben Paketquelle; **nur teilweise belastbar** ist ein erfolgreicher manueller Test in einer anderen Sitzung; **nicht belastbar** ist die bloße Tatsache, dass der Gesamtauftrag nach einer Änderung einmal grün wurde, wenn weder URL, Konto noch aufgelöste Revisionen dokumentiert sind.

Reparatur nach Befund auswählen

Vergleichen Sie die Optionen anhand des nachgewiesenen Fehlers, nicht anhand der Bequemlichkeit einer einzelnen Änderung:

  • URL oder Repository-Pfad korrigieren: Geeignet, wenn der Auftrag nachweislich eine falsche oder nicht mehr gültige Quelle anspricht. Danach Erreichbarkeit und Revision separat testen.
  • Zugriff für den Ausführungsbenutzer einrichten: Geeignet, wenn der Server erreichbar ist, aber die Zugangsdaten des tatsächlichen macOS-Kontos fehlen oder nicht verwendet werden. Schlüssel, Agent und Hostschlüsselprüfung gemeinsam verifizieren.
  • Xcode-Cloud-Autorisierung erneuern oder ergänzen: Geeignet, wenn der Arbeitsablauf Xcode Cloud verwendet und der dokumentierte SCM-Zugriff für das private Paket fehlt. Lokale SSH-Konfiguration ist hierfür kein Ersatz.
  • Lockdatei und Auflösung korrigieren: Geeignet, wenn der Paketabruf gelingt, aber die gewählten Revisionen nicht reproduzierbar sind. Lockdatei und Projektstand gemeinsam prüfen.
  • Swift-Code untersuchen: Erst wenn das Paket erfolgreich abgerufen und aufgelöst wurde, ist ein Compilerfehler ein Anlass, den Quellcode oder die Build-Einstellungen zu ändern.

Abnahme-Checkliste

  • [ ] Erster Fehler im Build-Protokoll gefunden und einer Phase zugeordnet.
  • [ ] Tatsächliche Repository-URL und verwendetes Protokoll identifiziert.
  • [ ] Erreichbarkeit und Repository-Pfad aus der Build-Umgebung nachgewiesen.
  • [ ] Tatsächlicher macOS-Ausführungsbenutzer festgestellt.
  • [ ] Zugangsdaten, SSH-Agent und Hostschlüsselprüfung für diesen Benutzer geprüft.
  • [ ] Bei Xcode Cloud der vorgesehene SCM-Autorisierungsablauf verwendet.
  • [ ] Relevante Package.resolved-Datei im erwarteten Projektstand geprüft.
  • [ ] Keine Schlüssel oder Token in Repository, URL, Skript oder Build-Ausgabe offengelegt.
  • [ ] Sauberer Build unter dem produktionsnahen Auftrag mit dokumentiertem Ergebnis abgeschlossen.

**Sicherheitsregel:** Wenn Sie nicht ausschließen können, dass ein Schlüssel in einem Protokoll oder einer URL sichtbar war, beheben Sie zuerst die mögliche Offenlegung. Ein erfolgreicher Build ist kein Beleg dafür, dass das Geheimnis weiterhin sicher ist.

Häufige Fragen zur privaten Paketauflösung

Weshalb funktioniert die Auflösung auf dem lokalen Mac, aber nicht beim Remote-Build?

Der lokale Auftrag kann als Ihr angemeldeter Benutzer laufen und dessen Git-Konfiguration, SSH-Schlüssel oder Agent verwenden. Der Remote-Auftrag startet möglicherweise unter einem Dienstkonto ohne dieselben Einstellungen. Vergleichen Sie Benutzer, Repository-URL und Authentifizierungsquelle im tatsächlichen Build-Auftrag. Wenn die Verbindung bereits am Netzwerk scheitert, ist fehlende Authentifizierung nicht die erste Ursache.

Wie richte ich SSH für private Pakete auf einem selbst gehosteten Mac ein?

Richten Sie den Zugriff für das macOS-Konto ein, das den Build tatsächlich ausführt, und testen Sie die Verbindung aus genau diesem Kontext. Prüfen Sie Schlüsselverfügbarkeit, Agent und Hostschlüsselprüfung, ohne private Inhalte auszugeben. Verwenden Sie danach denselben Repository-Pfad wie im Build. Änderungen an gemeinsam genutzten Git-Einstellungen sollten Sie erst übernehmen, wenn ihre Auswirkungen auf andere Aufträge geklärt sind.

Wie unterscheidet sich die Freigabe in Xcode Cloud?

Für Xcode Cloud müssen Sie den von Apple dokumentierten SCM-Autorisierungsweg für das private Repository nutzen und dessen aktuelle Voraussetzungen in der Plattformoberfläche überprüfen. Kopieren Sie nicht einfach SSH-Schlüssel oder lokale Benutzerkonfiguration eines selbst gehosteten Macs. Der Cloud-Auftrag muss die Paketquelle über seine eigene autorisierte Verbindung erreichen können.

Muss Package.resolved in den Versionsverlauf?

Wenn Ihr CI-Build die festgelegten Paketrevisionen reproduzierbar verwenden soll, prüfen Sie anhand von Apples CI-Dokumentation, ob die maßgebliche Package.resolved-Datei versioniert und im erwarteten Projektstand enthalten ist. Eine fehlende Datei kann zu einer anderen Auflösung führen. Sie behebt aber weder verweigerte Repository-Berechtigungen noch Netzwerkfehler; diese Ursachen müssen Sie separat nachweisen.

Wenn der Fehler nach diesen Prüfungen weiterhin an der selbst gehosteten Build-Umgebung hängt, vergleichen Sie den Aufwand für einen dauerhaft erreichbaren Mac mit Ihrem tatsächlichen Arbeitsablauf. Ein eigener Rechner bindet Kapital und erfordert laufende Pflege, Betriebssystem- und Zugangsdatenverwaltung sowie eine stabile Netzwerkverbindung; ein allgemeiner Cloud-Build löst nicht automatisch jede Abhängigkeit von einer konkreten macOS-Benutzerkonfiguration. Für sporadische Builds oder reproduzierbare Tests kann ein gemieteter Remote Mac flexibler sein, während ein dauerhaft stark ausgelasteter Rechner oder benötigte physische Anschlüsse eher für eigene Hardware sprechen. Informieren Sie sich über die Remote-Mac-Umgebung von MACGPU und prüfen Sie die Mietoptionen für einen Mac, bevor Sie entscheiden, ob ein separater macOS-Build-Rechner in Ihren Prozess passt.