Was tun, wenn Xcode Cloud private Abhängigkeiten nicht abrufen kann? Fehlerbehebung 2026

Der Build scheitert beim Abruf eines privaten Pakets oder Git-Submoduls – im Bericht steht aber nicht automatisch die Ursache.

Prüfen Sie zuerst, ob der Fehler beim Repository-Zugriff, bei der Abhängigkeitsauflösung oder in einem benutzerdefinierten Skript auftritt; private Abhängigkeiten allein sind kein Grund, Xcode Cloud aufzugeben.

Dieser Leitfaden richtet sich an Ingenieurinnen und Ingenieure, die Xcode-Cloud-Workflows betreuen und Fehler anhand des Build-Berichts eingrenzen möchten.
Teams mit internen Swift Packages, Git-Submodulen oder Abhängigkeiten aus mehreren Repositorys finden Hinweise zur Autorisierung und Auflösung.
IT- und Technikverantwortliche können anhand der tatsächlichen Netzwerk- und Werkzeuganforderungen entscheiden, ob ein selbstverwalteter Mac-Knoten geprüft werden sollte.

Zuerst die fehlerhafte Build-Phase bestimmen

Ein ähnlicher Fehlertext kann auf unterschiedliche Ursachen hindeuten. Lesen Sie im Build-Bericht zuerst, an welcher Stelle der Ablauf abbricht: beim Klonen des App-Repositorys, beim Laden einer Abhängigkeit, beim Ausführen eines Skripts oder beim Xcode-Build. Ein einzelner Hinweis wie „Repository nicht verfügbar“ beweist für sich allein noch nicht, ob die Verbindung fehlt, ein Zugriff verweigert wird oder das Skript einen falschen Pfad verwendet.

Die folgende Einordnung hilft Ihnen, die nächste Prüfung auf die passende Fehlerklasse zu begrenzen. Die Bewertungen sind eine praktische Orientierung für die Fehlersuche, keine Aussage über die Wahrscheinlichkeit einer Ursache.

Apple weist darauf hin, dass Xcode Cloud Abhängigkeiten oder erforderliche Werkzeuge unter Umständen nicht verfügbar sind und ein Build dadurch fehlschlagen kann. Das ist ein Anlass, den konkreten Zugriffspfad zu untersuchen – nicht der Nachweis, dass die Plattform grundsätzlich ungeeignet ist. Lesen Sie dafür Apples Hinweise zu Abhängigkeiten und privatem Zugriff in Xcode Cloud.

Für einen ersten Durchlauf notieren Sie die letzte erfolgreiche Aktion im Bericht, den Namen des betroffenen Repositorys oder Werkzeugs und den ausführenden Schritt. Vergleichen Sie diese Angaben anschließend mit dem lokalen Workflow. Wenn lokal und in Xcode Cloud unterschiedliche Paketstände oder Eingabedateien verwendet werden, ist ein bloßer Wiederholungsbuild kein verlässlicher Test.

Private Repositorys und Instanzen gezielt autorisieren

Wenn der Bericht bereits beim Zugriff auf Quellcode scheitert, prüfen Sie getrennt, ob Xcode Cloud auf das Haupt-Repository und auf jedes private Repository zugreifen kann, aus dem der Build tatsächlich liest. Dazu können ein internes Swift Package, ein Git-Submodul oder ein Repository gehören, das ein Skript während des Builds abruft. Ein erfolgreicher Zugriff auf den App-Code bestätigt nicht automatisch den Zugriff auf diese weiteren Quellen.

Apples Beschreibung der Einrichtung von Quellcodeverwaltung für Xcode Cloud behandelt die Verbindung zu unterstützten Repositorys. Prüfen Sie in den Projekteinstellungen, welcher Code-Hosting-Dienst verbunden ist, und vergleichen Sie ihn mit dem Ort, an dem das betroffene Paket oder Submodul tatsächlich liegt. Verlassen Sie sich nicht auf den Repository-Namen allein: Bei mehreren Organisationen, Konten oder getrennten Instanzen kann ein ähnlich benanntes Repository an einem anderen Ort liegen.

Wo prüfen Sie den Zugriff auf ein privates Swift Package?

Beginnen Sie bei der Paketquelle, die das Projekt verwendet, und prüfen Sie, ob diese Quelle für den Xcode-Cloud-Workflow erreichbar ist. Wenn ein Build-Bericht einen fehlenden Zugriff meldet, nutzen Sie den dort angebotenen Ablauf zur Freigabe beziehungsweise Autorisierung für das betroffene Repository. Prüfen Sie danach in einem neuen Build, ob sich die Fehlermeldung verändert. Ein geänderter Fehler kann bedeuten, dass die Autorisierung jetzt greift, aber ein nachgelagerter Schritt weiterhin fehlschlägt.

Stellen Sie außerdem sicher, dass die URL der Paketquelle und die tatsächlich verbundene Code-Hosting-Instanz zusammenpassen. Eine Berechtigung für das Haupt-Repository hilft nicht, wenn das Package in einem anderen privaten Repository liegt. Apples Dokumentation zur Bereitstellung von Abhängigkeiten ist der maßgebliche Ausgangspunkt für die Prüfung solcher privaten Abhängigkeiten.

Wie wird ein privates Git-Submodul berücksichtigt?

Behandeln Sie ein Submodul als eigenen Zugriffspfad. Ermitteln Sie zuerst, welche URL in der Submodul-Konfiguration steht, und vergleichen Sie diese mit dem Repository, das im Build-Bericht genannt wird. Prüfen Sie, ob die Verbindung zu genau diesem Repository besteht und ob die im Workflow verwendete Revision erreichbar ist. Wenn ein Skript das Submodul zusätzlich oder abweichend initialisiert, untersuchen Sie auch diesen Abruf separat.

Verwenden Sie die Meldung des Builds als Wegweiser: Sie kann zeigen, an welcher Quelle der Zugriff scheitert, erklärt aber nicht zwingend, ob die Ursache in der URL, der Verbindung oder dem Berechtigungsstatus liegt. Leiten Sie daraus keine allgemeine Aussage über Konten oder Teamrollen ab, bevor Sie die tatsächliche Quelle überprüft haben.

Hinweis: Wenn App-Code und Abhängigkeit auf unterschiedlichen Repository-Instanzen liegen, testen Sie beide Zugriffe getrennt. Ein erfolgreiches Klonen des App-Projekts ist kein Beleg dafür, dass eine zweite Instanz bereits angebunden ist.

Mehrere Instanzen desselben Anbieters

Unterscheiden Sie zwischen mehreren Instanzen desselben Code-Hosting-Dienstes und Repositorys bei unterschiedlichen Diensten. Wenn die Anwendung und eine private Abhängigkeit in verschiedenen Instanzen liegen, kann die erste eingerichtete Verbindung nur einen Teil des benötigten Zugriffs abdecken. Prüfen Sie die Instanz, die im Repository-Pfad oder in der Quelle der Abhängigkeit tatsächlich angegeben ist.

Apple beschreibt, dass eine noch nicht verbundene Instanz auch nach der ersten Einrichtung durch einen späteren Build-Hinweis auffallen kann. Folgen Sie in diesem Fall dem Zugriffshinweis des betroffenen Builds, statt die Verbindung der bereits funktionierenden Instanz wiederholt neu einzurichten. Die Einrichtungsanleitung für den ersten Xcode-Cloud-Workflow erläutert die Projekt- und Verbindungseinrichtung. Sie ersetzt jedoch nicht die Prüfung des konkreten Repository-Pfads.

Paketauflösung und Package.resolved abgleichen

Wenn der Zugriff auf das Repository gelingt, der Build aber bei der Auflösung eines Swift Packages abbricht, vergleichen Sie den Paketstand im Build mit dem Stand, den das Team lokal erwartet. Prüfen Sie, ob Package.resolved im Versionsverwaltungssystem erfasst ist, ob die Datei am erwarteten Projektpfad liegt und ob sie zum verwendeten Projekt- beziehungsweise Workspace-Stand gehört.

Package.resolved hält den aufgelösten Versionsstand von Swift-Package-Abhängigkeiten fest. Fehlt die Datei im erwarteten Pfad oder wurde sie nicht mit dem passenden Projektstand eingecheckt, kann die CI-Umgebung einen anderen Auflösungszustand vorfinden als die Entwicklerumgebung. Apples Leitfaden zu Swift Packages in kontinuierlichen Integrationsabläufen beschreibt die Anforderungen an Paketdateien und deren Einsatz in CI. Leiten Sie aus einer fehlenden Datei nicht ohne Prüfung ab, dass jede Xcode-Cloud-Konfiguration auf dieselbe Weise scheitern muss.

Gehen Sie die Unterschiede konkret durch: Ist die Datei im Branch des fehlgeschlagenen Builds enthalten? Liegt sie im Projektverzeichnis, das der Workflow tatsächlich verwendet? Wurde sie nach einer Paketänderung aktualisiert, aber nicht committet? Gibt es lokal Änderungen, die im Build-Commit fehlen? Diese Vergleiche trennen einen nicht verfügbaren Paketstand von einem reinen Autorisierungsproblem.

Package.resolved fehlt oder wurde nicht eingecheckt

Fehlt die Datei oder ist sie nicht Teil des erwarteten Commits, kann der Build eine Abhängigkeitsauflösung durchführen, die nicht dem lokal getesteten Zustand entspricht. Damit wird eine Versionsabweichung zu einem plausiblen Prüfpunkt, aber noch nicht zur bestätigten Ursache. Vergleichen Sie zunächst den Commit des fehlgeschlagenen Builds mit dem Projektzustand, den Sie lokal erfolgreich gebaut haben.

Erzwingen Sie nicht routinemäßig eine automatische Neuauflösung als vermeintliche Reparatur. Wenn das eigentliche Problem ein nicht autorisiertes Repository ist, kann eine erneute Auflösung denselben Zugriff verweigert bekommen; wenn es um einen fehlenden Commit geht, kann sie zusätzlich einen anderen Paketstand erzeugen. Sichern Sie zuerst den gewünschten Zustand im Repository und testen Sie danach mit einem neuen Build. Bei Änderungen an der Paketkonfiguration dokumentieren Sie, welche Änderung den Fehler tatsächlich beseitigt hat.

Drittanbieterwerkzeuge und Skripte im tatsächlichen Kontext prüfen

Wenn das Repository erreichbar ist und die Swift-Paketauflösung nicht der Fehlerpunkt ist, untersuchen Sie Werkzeuge wie CocoaPods oder Carthage sowie weitere im Projekt verwendete Hilfsprogramme. Prüfen Sie, ob die verwendeten Lockdateien versioniert sind, welches Installationsverfahren der Workflow ausführt und ob dieses Verfahren im Build-Bericht tatsächlich vor dem Schritt ausgeführt wird, der das Werkzeug benötigt.

Ein temporärer Build-Kontext darf nicht stillschweigend auf den Zustand eines Entwickler-Macs angewiesen sein. Wenn lokal ein Werkzeug bereits installiert, eine Datei vorhanden oder eine Umgebungsvariable gesetzt ist, muss der Workflow die benötigten Voraussetzungen selbst nachvollziehbar bereitstellen. Ermitteln Sie, welche Befehle im fehlgeschlagenen Build protokolliert sind, und führen Sie die Prüfung nicht nur anhand einer erfolgreichen lokalen Ausführung durch.

Bei selbst geschriebenen Skripten sind Zeitpunkt und Ort entscheidend. Apple dokumentiert die Ausführung von benutzerdefinierten Build-Skripten unter anderem als post-clone, pre-xcodebuild und post-xcodebuild – damit sind drei konkrete Ausführungspunkte benannt, die Sie im Workflow-Bericht und in der Skriptbenennung abgleichen können. Die Details stehen in Apples Dokumentation zu benutzerdefinierten Build-Skripten.

Prüfen Sie für jeden betroffenen Schritt:

1. Stimmt der erwartete Skriptname mit dem Namen und Speicherort im Repository überein?
2. Ist das Skript im Branch des fehlgeschlagenen Builds enthalten?
3. Sind die benötigten Dateien vorhanden, bevor das Skript sie öffnet?
4. Gibt das Skript bei einem Fehler einen passenden Status zurück, oder läuft der Fehler unbemerkt weiter?
5. Verwendet es Umgebungsvariablen, die im Build-Kontext tatsächlich gesetzt und dokumentiert sind?

Verlassen Sie sich nicht auf angenommene Administratorrechte oder auf implizite Zustände der lokalen Entwicklungsumgebung. Ein Skript, das lokal funktioniert, belegt nicht, dass seine Voraussetzungen im CI-Kontext erfüllt sind. Machen Sie die benötigten Schritte ausdrücklich und überprüfen Sie die Protokolle, bevor Sie dem Ausführungsdienst oder dem Werkzeug selbst die Schuld geben.

Erfahrungshinweis: Wenn ein Skript sensible Werte ausgibt, behandeln Sie das als mögliches Offenlegungsrisiko. Prüfen Sie die Protokollausgabe auf Zugangsdaten und vermeiden Sie es, geheime Werte zu Diagnosezwecken direkt auszugeben.

Umgebungsvariablen, Netzwerk und Zugangsdaten

Wenn der Fehler erst beim Aufruf eines internen Dienstes oder beim Abruf eines Werkzeugs auftritt, klären Sie zunächst, welche Adresse der Build erreichen muss, ob ein Proxy erforderlich ist und wie Zugangsdaten bereitgestellt werden. Prüfen Sie im Build-Bericht, ob der Fehler vor oder nach dem Netzwerkaufruf entsteht. So vermeiden Sie, eine fehlerhafte Paketauflösung mit einer Netzwerkstörung zu verwechseln.

Apple stellt eine Referenz der Xcode-Cloud-Umgebungsvariablen sowie eine Übersicht der Workflow-Variablen bereit. Verwenden Sie diese Quellen, um zu prüfen, welche Werte im jeweiligen Kontext verfügbar sind, statt Variablennamen oder lokale Einstellungen vorauszusetzen. Geben Sie sensible Werte nicht in Build-Protokollen aus; kontrollieren Sie auch, ob Debug-Ausgaben, Shell-Befehle oder Fehlermeldungen einen geheimen Wert indirekt sichtbar machen.

Für Anforderungen an ein privates Unternehmensnetz sollten Sie vor einer Änderung der CI-Umgebung schriftlich festhalten, welche Zielsysteme erreicht werden müssen, über welche Verbindung das geschehen soll und welche Werkzeuge dafür zwingend erforderlich sind. Erst wenn der konkrete Zugriffspfad belegt ist und sich mit dem bestehenden Workflow nicht abbilden lässt, ist eine Bewertung eines selbstverwalteten Mac-Knotens sinnvoll. Das ist eine Prüfung der Umgebungsanforderungen, keine automatische Schlussfolgerung aus einem fehlgeschlagenen Build.

Prüfablauf vor der Änderung des CI-Systems

Arbeiten Sie die folgenden Punkte am betroffenen Branch und anhand des tatsächlichen Build-Berichts ab. Markieren Sie einen Punkt erst dann als erledigt, wenn die passende Änderung in einem erneuten Build geprüft wurde.

• [ ] Fehlerphase im Build-Bericht festgehalten: Klonen, Abhängigkeitsauflösung, Skript oder Xcode-Build.
• [ ] Betroffenes Repository beziehungsweise Paket anhand seiner tatsächlichen Quelle identifiziert.
• [ ] Zugriff auf Haupt-Repository und private Abhängigkeiten getrennt geprüft.
• [ ] Bei mehreren Repository-Instanzen die verwendete Instanz mit der eingerichteten Verbindung abgeglichen.
• [ ] Package.resolved im passenden Projektpfad und im Commit des fehlgeschlagenen Builds kontrolliert.
• [ ] Lockdateien und Installationsschritte der Drittanbieterwerkzeuge überprüft.
• [ ] Skriptnamen, Speicherorte, Ausführungszeitpunkt und Rückgabestatus abgeglichen.
• [ ] Netzwerkziele, Proxy-Anforderungen und verfügbare Umgebungsvariablen dokumentiert.
• [ ] Protokolle auf versehentlich ausgegebene Zugangsdaten geprüft.
• [ ] Nach jeder gezielten Änderung einen neuen Build ausgeführt und das Ergebnis mit dem vorherigen Bericht verglichen.

Wenn Sie auch andere Ausführungsumgebungen prüfen, hilft ein Vergleich der verfügbaren Mac-Optionen, die Anforderungen an Zugriff, Betriebsmodell und Verantwortlichkeiten strukturiert gegenüberzustellen. Für eine konkrete Mac-Umgebung finden Sie außerdem Informationen zur Mac-mini-Nutzung im Rechenzentrum. Prüfen Sie dabei immer, ob die jeweilige Umgebung Ihre tatsächlichen Netzwerk- und Werkzeuganforderungen erfüllt; eine Produktübersicht ist kein Nachweis für die Erreichbarkeit Ihres privaten Repositorys.

Wann ein selbstverwalteter Mac-Knoten in Betracht kommt

Bleibt nach der Diagnose eine nachweisbare Anforderung übrig, die Ihr Xcode-Cloud-Workflow nicht erfüllt – etwa ein notwendiger Zugriff auf ein bestimmtes privates Netz oder ein intern vorgeschriebenes Werkzeug –, dokumentieren Sie zuerst diese Anforderung und die bisher geprüften Alternativen. Ein selbstverwalteter Mac-Knoten kann mehr Kontrolle über installierte Werkzeuge und die Einbindung in die eigene Umgebung ermöglichen. Dafür übernimmt Ihr Team auch Verantwortung für Zugriffsschutz, Aktualisierung, Überwachung und den Betrieb des Knotens.

Vergleichen Sie deshalb nicht nur, ob ein Build „irgendwie läuft“, sondern auch, wer die Umgebung verwaltet und welche Sicherheitskontrollen nötig sind. Wenn Ihr Team einen dauerhaft betriebenen Knoten mit fest definierten Schnittstellen und eigenem Betriebsprozess benötigt, kann die eigene Infrastruktur angemessen sein. Für einen zeitlich begrenzten Test oder eine zusätzliche macOS-Umgebung kann die Miete eines Mac von zshmac eine Alternative zum Kauf und zur lokalen Wartung sein. Sie sollten aber vorab prüfen, ob der konkrete Zugriff auf Ihr internes Netzwerk und Ihre Werkzeuge möglich ist; ohne diesen Nachweis ist weder eine Miet- noch eine Kaufentscheidung belastbar.

Wenn die Fehleranalyse zeigt, dass der Workflow lediglich eine fehlende Freigabe, einen abweichenden Paketstand oder ein unvollständiges Skript hat, beheben Sie genau diesen Punkt und behalten Sie Xcode Cloud zunächst bei. Müssen Ihre Builds dagegen auf ein privates Netz oder eine kontrollierte Werkzeugumgebung zugreifen, die sich mit dem bestehenden Workflow nicht abbilden lässt, prüfen Sie zuerst die Anforderungen und testen Sie eine Mac-Umgebung gezielt. Für einen solchen zeitlich begrenzten Infrastrukturtest können Sie sich bei zshmac über die verfügbaren Mietoptionen informieren; entscheiden Sie erst nach erfolgreicher Prüfung des tatsächlichen Repository-Zugriffs, ob ein Wechsel Ihres Build-Ausführungsorts sinnvoll ist.