Trennen Sie drei Dinge, bevor Sie eine Variable anlegen: gewöhnliche Konfiguration, vertrauliche Zugangsdaten und Dateien, die ein Build benötigt. Diese Trennung entscheidet, ob ein Wert als normale Variable, als Secret oder über einen kontrollierten Bereitstellungsschritt behandelt werden sollte.

Eine Region, ein nicht vertraulicher Schalter oder ein Name für eine Testumgebung kann in der Regel als normale Umgebungsvariable behandelt werden. Ein API-Token, ein Kennwort oder ein anderer Wert, mit dem ein externer Dienst Zugriff gewährt, ist dagegen ein Secret. Schreiben Sie Zugangsdaten nicht fest in ein Skript und legen Sie sie nicht in einer Projektdatei ab, die in Ihrem Repository landet.

Angenommen, ein Skript lädt nach dem Build Symbole zu einem externen Dienst hoch. Es benötigt dafür ein Zugriffstoken. Wird der Wert mit echo ausgegeben oder aktiviert das Skript eine ausführliche Shell-Protokollierung, kann er im Build-Protokoll auftauchen. In diesem Fall reicht es nicht, die Variable lediglich „irgendwie“ in Xcode Cloud einzutragen: Sie müssen ihren Typ, ihren Einsatzort und die Ausgabewege gemeinsam prüfen.

Die Apple-Dokumentation zu benutzerdefinierten Build-Skripten beschreibt die Verarbeitung von Secrets in Skripten und Protokollen. Ergänzend erklärt Apples Referenz der Xcode-Cloud-Umgebungsvariablen, welche Variablen Xcode Cloud selbst bereitstellt. Verwechseln Sie diese vordefinierten Werte nicht mit Variablen, die Sie selbst anlegen: Der Ursprung und die Bedeutung eines Werts sind unterschiedlich.

Auch Dateien brauchen eine eigene Entscheidung. Eine Konfigurationsdatei mit nicht vertraulichen Einstellungen kann zum Projekt gehören. Ein Zertifikat, ein privater Schlüssel oder ein Export einer Zugangsdatenverwaltung gehört nicht unbesehen ins Repository. Prüfen Sie, ob die Datei tatsächlich als Build-Eingabe benötigt wird und ob der vorgesehene Bereitstellungsweg Ihre Anforderungen erfüllt. Die Variable ist kein Ersatz für einen sicheren Umgang mit Dateien.

Legen Sie eine Variable zunächst dort an, wo ihr Einsatz nachvollziehbar bleibt. Benötigt nur der Release-Workflow ein Upload-Token, sollte es nicht automatisch auch in Test- und Pull-Request-Workflows verfügbar sein. Für Einstellungen, die mehrere Abläufe tatsächlich teilen müssen, können Sie eine gemeinsam genutzte Variable verwenden.

Die Tabelle ist eine Entscheidungshilfe, keine Aussage, dass jede Variable beliebig zwischen diesen Kategorien wechseln kann. Ob eine Einstellung für Ihren Workflow verfügbar ist und wie die Oberfläche sie bezeichnet, sollten Sie anhand der Apple-Anleitung zum Teilen von Umgebungsvariablen zwischen Xcode-Cloud-Workflows prüfen. Apple kann die Oberfläche ändern; verlassen Sie sich nicht auf einen gespeicherten Screenshot oder eine ältere interne Anleitung.

Gehen Sie bei der Einrichtung in dieser Reihenfolge vor:

1. Benennen Sie den Zweck. Notieren Sie, welches Skript den Wert benötigt und welche Build-Aufgabe davon abhängt. Ein Name wie UPLOAD_TOKEN ist leichter zu prüfen als eine mehrdeutige Abkürzung.
2. Bestimmen Sie den Schutzbedarf. Ist der Wert ein Zugangsnachweis oder ermöglicht er schreibenden beziehungsweise veröffentlichenden Zugriff, behandeln Sie ihn als Secret. Ein nicht vertraulicher Schalter braucht diese Einstufung nicht.
3. Wählen Sie den kleinsten sinnvollen Geltungsbereich. Nutzen Sie eine Workflow-Variable für einen einzelnen Ablauf. Teilen Sie einen Wert nur dann workflowübergreifend, wenn die betroffenen Abläufe ihn wirklich brauchen.
4. Prüfen Sie Zuständigkeiten. Stellen Sie sicher, dass Personen, die Workflows bearbeiten oder Variablen verwalten können, ihrer Teamrolle entsprechend Zugriff erhalten. Apples Hinweise zur Workflow-Strategie und zu Bearbeitungsrechten helfen bei dieser Abgrenzung.
5. Speichern Sie keine echten Zugangsdaten in Testausgaben. Verwenden Sie für einen ersten Funktionstest einen erkennbaren, nicht produktiven Platzhalter. Ein echter Dienstschlüssel ist kein geeignetes Diagnosemittel.

„Gemeinsam genutzt“ bedeutet dabei nicht „für alle Workflows freigeben“. Ein gemeinsamer Wert kann die Wartung vereinfachen, erweitert aber zugleich den Kreis möglicher Nutzer. Prüfen Sie die Zuweisung deshalb bei jeder Änderung an Workflows und Teamrollen erneut.

Wichtig: Die Maskierung eines Secret-Werts im Protokoll bedeutet nicht, dass die Zugangsdaten unabhängig vom Workflow-Auslöser sicher eingesetzt werden können. Log-Schutz und Berechtigungsgrenzen sind zwei getrennte Prüfungen.

Ein benutzerdefiniertes Skript sollte nur die Werte verwenden, die seine Aufgabe benötigt. Der passende Zeitpunkt hängt davon ab, ob Sie Abhängigkeiten vorbereiten, vor dem Xcode-Build Dateien oder Einstellungen prüfen oder nach dem Build ein Artefakt weiterverarbeiten. Apple beschreibt die verfügbaren Skriptphasen und deren Rahmen in der Referenz für Xcode-Cloud-Workflows.

Ordnen Sie die Phasen nach ihrer Funktion, statt ein einzelnes Skript für alles zu verwenden:

• post-clone eignet sich für Aufgaben unmittelbar nach dem Klonen des Projekts, etwa eine frühe Prüfung oder Vorbereitung. Gehen Sie nicht davon aus, dass bereits erzeugte Build-Artefakte vorhanden sind.
• pre-xcodebuild liegt vor dem eigentlichen Xcode-Build. Nutzen Sie diese Phase für Vorbereitungen, die der Build benötigt, und prüfen Sie dabei, ob die erforderlichen Projektressourcen schon verfügbar sind.
• post-xcodebuild folgt auf den Build. Hier können nachgelagerte Aufgaben wie eine kontrollierte Verarbeitung des Ergebnisses stattfinden. Ein Upload-Token gehört nur dann in diesen Ablauf, wenn der Upload tatsächlich ausgeführt werden soll.

Die exakten Rahmenbedingungen, verfügbaren Ressourcen und dokumentierten Variablen können von der Phase abhängen. Prüfen Sie dafür Apples Beschreibung benutzerdefinierter Build-Skripte und die Umgebungsvariablen-Referenz. Übertragen Sie Annahmen aus einem lokalen Terminal nicht automatisch auf einen Xcode-Cloud-Build: Lokale Dateien, installierte Werkzeuge und persönliche Shell-Einstellungen müssen dort nicht vorhanden sein.

Ein Skript sollte bei einer fehlenden Pflichtvariable kontrolliert abbrechen. Ein einfaches Muster ist:

if [ -z "${UPLOAD_TOKEN:-}" ]; then
  echo "Erforderliche Upload-Konfiguration fehlt."
  exit 1
fi

Das Beispiel prüft, ob ein Wert vorhanden ist, und gibt den Inhalt nicht aus. Verwenden Sie für Ihren Test einen nicht vertraulichen Platzhalter. Ergänzen Sie danach nur die nötige Aktion, ohne den Token selbst in Fehlermeldungen, Debug-Ausgaben oder Befehlszeilen zu schreiben. Vermeiden Sie insbesondere Shell-Tracing, wenn dadurch expandierte Werte protokolliert werden könnten.

Wenn das Skript eine Variable nicht findet, beginnen Sie bei der Konfiguration und nicht mit dem Ausgeben des Werts. Kontrollieren Sie den Variablennamen einschließlich Groß- und Kleinschreibung, die Zuweisung an den tatsächlich gestarteten Workflow und die Phase, in der das Skript läuft. Prüfen Sie außerdem, ob ein lokaler Test eine Datei oder Shell-Einstellung voraussetzt, die im Cloud-Build fehlt.

Ein Secret ist nur so gut geschützt wie der Weg, auf dem es verwendet wird. Prüfen Sie neben der Secret-Kennzeichnung, welcher Workflow den Wert erhält, wer den Workflow ändern kann und welche Aufgaben den betreffenden Code ausführen. Dazu zählen etwa Änderungen an einem Branch, Pull Requests, manuelle Starts und Release-Abläufe. Bewerten Sie diese Auslöser getrennt, statt aus der Bezeichnung „Secret“ eine pauschale Freigabe abzuleiten.

Diese Unterscheidung ist für kleine Teams praktisch wichtig. Ein Skript kann in einem Release-Workflow einen externen Upload durchführen, während ein Testlauf lediglich kompilieren soll. Wenn beide Workflows denselben Token bekommen, erhöht das die Zahl der Abläufe, in denen er verarbeitet werden kann, ohne dass der Test dadurch notwendigerweise einen Nutzen erhält. Halten Sie die Variable dort zurück, wo sie nicht gebraucht wird.

Prüfen Sie die Berechtigungen anhand der Apple-Hinweise zur Workflow-Strategie. Sehen Sie sich danach das Build-Protokoll und den Bericht an. Apples Hinweise zum Berichten von Feedback für Xcode Cloud machen deutlich, dass Skriptprotokolle Teil der Diagnose sind. Behandeln Sie sie deshalb wie Ausgaben, die keine Zugangsdaten enthalten dürfen.

Ihre Prüfung sollte mindestens diese Punkte umfassen:

• Das Skript gibt weder den Secret-Wert noch eine zusammengesetzte Ausgabe aus, die ihn enthält.
• Fehlertexte nennen den fehlenden Konfigurationsnamen, aber nicht den vertraulichen Inhalt.
• Ein fehlender Pflichtwert führt zu einem verständlichen Fehlerstatus statt zu einem scheinbar erfolgreichen, aber unvollständigen Build.
• Die Prüfung erfolgt mit einem unkritischen Testwert, bevor ein produktiver Dienstschlüssel verwendet wird.
• Der erfolgreiche und der absichtlich fehlschlagende Lauf werden beide in den Build-Ausgaben kontrolliert.

Ein im Log verdeckter Wert ist kein Beweis dafür, dass jede Verwendung sicher ist. Ein Skript könnte einen Secret-Wert an ein externes Ziel senden oder ihn an einen weiteren Prozess weitergeben. Begrenzen Sie daher auch, was der aufgerufene Dienstschlüssel darf: Verwenden Sie, sofern der jeweilige Dienst das unterstützt, einen für den konkreten Zweck geeigneten Zugriff und prüfen Sie dessen Verwaltung separat. Diese Sicherheitsentscheidung ersetzt die Xcode-Cloud-Konfiguration nicht, sondern ergänzt sie.

Ein lokaler erfolgreicher Lauf beweist nicht, dass die Cloud-Konfiguration stimmt. Der Build muss den richtigen Workflow treffen, die Variable in der vorgesehenen Phase lesen und sich im Fehlerfall erwartungsgemäß verhalten. Planen Sie die Abnahme deshalb als eigenen Arbeitsschritt und nicht als beiläufige Folge eines Release-Builds.

1. Starten Sie mit einem nicht sensiblen Wert. Lassen Sie das Skript nur das Vorhandensein bestätigen. Protokollieren Sie nicht den Inhalt.
2. Prüfen Sie den vorgesehenen Workflow. Stellen Sie fest, dass die Variable tatsächlich dem Ablauf zugewiesen ist, der den Test ausführt.
3. Testen Sie den Fehlerpfad. Entfernen Sie die Testvariable oder verwenden Sie einen separaten Testfall, der den fehlenden Wert simuliert. Das Skript sollte mit einer klaren Meldung und einem Fehlerstatus enden.
4. Kontrollieren Sie die Ausgabe. Prüfen Sie Build-Log und Bericht auf ausgegebene Werte, Shell-Tracing, versehentliche Umgebungsdump-Ausgaben und missverständliche Erfolgsmeldungen.
5. Führen Sie die Prüfung im Zielablauf aus. Erst wenn der harmlose Test funktioniert, prüfen Sie den tatsächlichen Ablauf mit den vorgesehenen Berechtigungen und dem dafür freigegebenen Secret.

Wenn Sie einen Secret-Wert erstmals einsetzen, beurteilen Sie nicht nur, ob die Aktion erfolgreich war. Fragen Sie auch, ob das Skript ihn länger oder in mehr Schritten als nötig verfügbar macht. Ein erfolgreicher Upload mit offenem Token im Log ist ein fehlgeschlagener Sicherheitstest.

Dokumentieren Sie im Team, welche Variablen zu welchem Workflow gehören, wer sie ändern darf und welche Skripte sie verwenden. Die Dokumentation sollte Namen und Zwecke enthalten, nicht die Werte selbst. Wenn ein Secret ersetzt oder widerrufen werden muss, hilft diese Zuordnung dabei, betroffene Abläufe zu finden, ohne den alten Wert in Notizen oder Tickets zu kopieren.

Xcode Cloud passt, wenn die benötigten Build-Schritte im dokumentierten Workflow ausführbar sind und Sie keinen dauerhaften Zustand auf einem Host voraussetzen. Prüfen Sie eine ergänzende Mac-Umgebung, wenn Sie für Ihre Arbeit einen dauerhaft verfügbaren Arbeitsbereich, interaktive Fehlersuche oder Kontrolle über den Hostzustand benötigen. Entscheiden Sie anhand eines konkreten Engpasses, nicht allein aufgrund der Annahme, ein Cloud-Build sei grundsätzlich ungeeignet.

Die rechte Spalte ist kein automatischer Grund zum Wechsel. Eine zusätzliche Umgebung bringt eigene Aufgaben mit: Sie müssen Zugang, Updates, Projektzustand und die Verwaltung von Zugangsdaten in den Ablauf einbeziehen. Umgekehrt kann ein Workflow, der interaktive Untersuchung oder einen dauerhaft verfügbaren Arbeitsbereich verlangt, mit einer reinen Build-Ausführung unnötig schwer zu warten sein.

Wenn Sie zunächst die Unterschiede zwischen einem Cloud-Workflow und einer eigenen Mac-Build-Umgebung prüfen möchten, vergleichen Sie Ihre Anforderungen mit den aktuellen Angaben auf der KVMNODE-Übersichtsseite. Verlassen Sie sich bei Verfügbarkeit, Zugangswegen und Bereitstellung auf die dort ausgewiesenen Informationen, nicht auf Annahmen aus einer allgemeinen Anleitung. Möchten Sie statt einer zusätzlichen Umgebung lieber lokale Hardware beschaffen, können Sie als Gegenoption die Informationen zum Mac mini M4 prüfen und Anschaffung, laufende Wartung und Nutzungsszenario selbst gegenüberstellen.

Wie legen Sie eine eigene Umgebungsvariable in Xcode Cloud an?

Öffnen Sie die Einstellungen des passenden Workflows und hinterlegen Sie dort Namen und Wert. Markieren Sie vertrauliche Inhalte als Secret, bevor ein Skript sie verwendet. Prüfen Sie anschließend die Zuweisung: Eine korrekt angelegte Variable hilft nicht, wenn der gestartete Workflow keinen Zugriff darauf hat. Da sich Oberflächenbezeichnungen ändern können, gleichen Sie die Schritte mit Apples aktueller Dokumentation ab.

Wie verhindern Sie, dass ein Secret im Build-Log erscheint?

Kennzeichnen Sie vertrauliche Werte als Secret und verhindern Sie, dass Skripte sie mit echo, Shell-Tracing oder ausführlichen Fehlermeldungen ausgeben. Testen Sie die Protokollierung zuerst mit einem Platzhalter. Prüfen Sie zusätzlich, welche Workflows und Auslöser das Secret verwenden können. Eine Log-Maskierung schützt die sichtbare Ausgabe, ersetzt aber keine Begrenzung des Zugriffs auf das Secret.

Können mehrere Workflows dieselben Variablen verwenden?

Gemeinsam genutzte Umgebungsvariablen können für mehrere Workflows vorgesehen werden. Geben Sie sie dennoch nur den Abläufen, die den jeweiligen Wert benötigen. Das gilt besonders für Zugangsdaten: Ein Test- oder Pull-Request-Workflow sollte nicht automatisch ein Release-Token erhalten, nur weil beide Abläufe denselben Variablennamen verwenden könnten. Halten Sie Zuweisungen und Zuständigkeiten nachvollziehbar.

Was tun Sie, wenn ein Skript die Variable nicht findet?

Kontrollieren Sie den Variablennamen, die Groß- und Kleinschreibung sowie die Zuordnung zum gestarteten Workflow. Prüfen Sie danach, ob das Skript in der erwarteten Phase läuft und die benötigten Ressourcen dort verfügbar sind. Geben Sie den Wert nicht zu Diagnosezwecken aus. Fehlt eine Pflichtvariable, sollte das Skript kontrolliert mit einer aussagekräftigen Meldung und einem Fehlerstatus abbrechen.

Wenn Ihre Xcode-Cloud-Abläufe ohne dauerhaften Zustand, interaktive Untersuchung oder zusätzliche Hostkontrolle auskommen, ist es meist sinnvoller, die Variablenzuweisung und Skripte gezielt zu verbessern, statt eine zweite Build-Umgebung einzuführen. Werden genau diese Anforderungen zum wiederkehrenden Hindernis, kann ein gemieteter Mac als ergänzende Umgebung besser zu Ihrer Arbeitsweise passen als ein ausschließlich flüchtiger Workflow. Prüfen Sie bei KVMNODE die aktuell ausgewiesenen Zugangs- und Mietoptionen, bevor Sie entscheiden, ob eine zusätzliche Mac-Umgebung den Aufwand für Ihr Projekt rechtfertigt.