Wie migrieren Sie den GitHub Actions Xcode 27 Runner? Abnahme-Checkliste 2026

Fehlerbild: Ein vorhandener iOS-Workflow soll auf den Xcode-27-Runner wechseln.
Schnellster sicherer Weg: Erst in einem separaten Branch testen, dann Toolchain, Signierung und Artefakt abnehmen und erst danach den produktiven Workflow umstellen.

GitHub meldete die allgemeine Verfügbarkeit des Xcode-27-Runner-Images am 15.10.2026. Das belegt die Verfügbarkeit des Images, nicht die Kompatibilität mit Ihrem Projekt. Für die Migration des GitHub Actions Xcode 27 Runners gilt deshalb: Tauschen Sie nicht bloß das Runner-Label aus und erklären Sie die Arbeit für erledigt. Prüfen Sie den Workflow in einem unabhängigen Branch und behalten Sie eine ausführbare Rückfallkonfiguration. Die Verfügbarkeitsmeldung steht im GitHub-Changelog zum Xcode-27-Runner-Image.

Zuletzt geprüft am 19.10.2026. Die Angaben zur Verfügbarkeit, zu Labels und Image-Inhalten sind anhand der verlinkten GitHub-Dokumentation geprüft. Xcode-Systemanforderungen und Distributionsabläufe sind mit den verlinkten Apple-Dokumenten abzugleichen.

Dieser Ablauf richtet sich an iOS-Entwickler, die ihre bestehenden GitHub-Actions-Builds auf den neuen Runner umstellen möchten.
Auch kleine Teams mit mehreren Apps oder Release-Zweigen können damit stufenweise testen und bei Problemen zurückschalten.
Wenn Sie Builds und Verteilung ohne lokalen Mac organisieren, hilft die Abnahme dabei, die Reproduzierbarkeit Ihrer CI-Umgebung zu beurteilen.

Vor dem Wechsel: Projektanforderungen und Rückfallziel

Beginnen Sie nicht mit der Änderung der Workflow-Datei, sondern mit einer Bestandsaufnahme. Notieren Sie, welche Xcode-Version und welche SDKs Ihr Projekt benötigt, welche Ziele gebaut werden und welche Abhängigkeiten vor dem Build installiert werden. Prüfen Sie die Anforderungen anhand der Apple-Seite zu Xcode-Versionen und Systemanforderungen. Die benötigte Toolchain muss zu Ihrem Projekt passen; dass eine neue Runner-Image-Version verfügbar ist, ersetzt diese Prüfung nicht.

Gehen Sie anschließend die vorhandene CI-Konfiguration durch und suchen Sie nach Annahmen, die nicht unmittelbar sichtbar sind:

• Verwendet ein Skript einen fest eingetragenen Pfad zu Xcode, einem Simulator oder einem Hilfsprogramm?
• Wird ein Werkzeug vorausgesetzt, das auf dem bisherigen Runner vorinstalliert war?
• Hängt ein Schritt von einer bestimmten Shell, einem Home-Verzeichnis oder einer Umgebungsvariablen ab?
• Werden Abhängigkeiten dynamisch geladen, statt auf eine nachvollziehbare Version festgelegt zu sein?
• Greifen mehrere Jobs auf dieselben Signierungs- oder Release-Secrets zu?

Das sind keine Beweise dafür, dass der neue Runner scheitern wird. Es sind Prüfstellen, an denen sich Unterschiede zwischen Images bemerkbar machen können. Die Dokumentation des Xcode-27-Runner-Images beschreibt Image-Inhalte und Architektur. Verwenden Sie diese Angaben statt einer Erinnerung an frühere Preview-Images oder einer alten Workflow-Vorlage.

Legen Sie vor dem Test fest, was als Rückfall gilt. Das kann die bisherige runs-on-Auswahl in einem separaten Commit oder eine unveränderte Workflow-Datei auf dem Hauptzweig sein. Entscheidend ist, dass Sie die alte Konfiguration bei einem Release-Blocker gezielt wieder aktivieren können, ohne zugleich andere Änderungen rückgängig machen zu müssen.

Szenario aus dem Entwickleralltag: Eine App baut in Pull Requests, archiviert aber nur im Release-Workflow. Ein erfolgreicher Testlauf im Pull Request beweist dann nicht, dass Zertifikat, Provisioning Profile und Exportkonfiguration beim Release funktionieren. Behandeln Sie diese Pfade als getrennte Abnahmen.

Beim ersten Commit: Nur die Runner-Auswahl ändern

Erstellen Sie einen Migrations-Branch und ändern Sie dort zunächst nur die Auswahl des macOS-Runners. Nehmen Sie keine gleichzeitige Umstellung von Abhängigkeiten, Build-Skripten oder Release-Aktionen vor. Andernfalls können Sie bei einem Fehler nicht mehr zuverlässig feststellen, ob die Ursache der Runner-Wechsel oder eine weitere Änderung war.

GitHub dokumentiert die Auswahl über runs-on in der Syntaxreferenz für Actions-Workflows. Übernehmen Sie das aktuelle Label aus der offiziellen Image-Dokumentation, statt ein Label aus einem älteren Beispiel zu erraten. Eine mögliche Organisationsform ist ein Repository-Variable als zentraler Wert:

jobs:
  build:
    runs-on: ${{ vars.IOS_MACOS_RUNNER }}

Hinterlegen Sie in IOS_MACOS_RUNNER das Label, das GitHub für Ihr gewünschtes Image aktuell dokumentiert. Diese Darstellung ist hilfreich, wenn mehrere Workflows denselben Runner verwenden: Sie können den zentralen Wert nach einer Prüfung ändern, statt verschiedene Workflow-Dateien einzeln zu durchsuchen. Die Variable macht eine Umstellung allerdings nicht automatisch sicher. Prüfen Sie ihren Inhalt, die Berechtigungen und die Jobs, die darauf zugreifen.

Die GitHub Actions macOS Runner-Auswahl sollte sich außerdem nicht allein am Namen orientieren. Vergleichen Sie die dokumentierte Architektur und Image-Inhalte mit den Anforderungen Ihrer Anwendung. Falls Sie mehrere Plattformen oder Runner-Klassen in einem Workflow verwenden, kontrollieren Sie jeden Job einzeln. Ein Build-Job kann auf dem neuen Image laufen, während ein separater Release-Job weiterhin ein anderes Umfeld voraussetzt.

Bewahren Sie im Pull Request den diff und einen Verweis auf das geprüfte Image-Label auf. So lässt sich später nachvollziehen, welches Image für die Freigabe vorgesehen war. Für die laufende Wartung ist diese Dokumentation besonders wichtig, wenn GitHub das Image ändert oder Ihr Team die Toolchain erneut prüft.

Beim ersten Lauf: Toolchain, Abhängigkeiten und Projektfehler trennen

Starten Sie mit einem manuellen oder nicht produktiven Workflow-Lauf. Kontrollieren Sie im Protokoll, welche Xcode-Version tatsächlich aktiv ist und welches SDK der Build verwendet. Nutzen Sie dafür die Kommandos, die Ihr Projekt bereits für die Umgebungsdiagnose verwendet, oder ergänzen Sie vorübergehend eine Ausgabe der installierten Werkzeuge. Verlassen Sie sich nicht darauf, dass der sichtbare Runner-Name automatisch die aktive Xcode-Auswahl beweist.

Ordnen Sie einen Fehler anschließend einer konkreten Ebene zu:

1. Runner oder Toolchain: Das Image, das Architekturmerkmal oder die aktive Xcode-Auswahl entspricht nicht der Projekterwartung. Vergleichen Sie Protokoll und Image-Beschreibung.
2. Abhängigkeiten: Das Auflösen oder Installieren von Paketen scheitert, bevor der eigentliche Projekt-Build beginnt. Prüfen Sie Lockfiles, Installationsschritte und Zugriff auf private Quellen.
3. Projekt oder Tests: Die Werkzeuge starten, aber Kompilierung oder Tests melden einen Fehler im Anwendungscode, in den Build-Einstellungen oder in einer projektspezifischen Konfiguration.

Diese Einteilung ist eine Diagnosehilfe, keine Behauptung über eine einheitliche Fehlerursache. Ein roter Workflow allein zeigt nicht, welche Ebene verantwortlich ist. Sichern Sie den relevanten Protokollabschnitt und vergleichen Sie ihn mit einem Lauf auf der bisherigen Runner-Konfiguration, bevor Sie Anpassungen am Projektcode vornehmen.

Zur Abnahme der iOS-Automatisierung gehören auch nicht offensichtliche Schritte: Werden die erwarteten Testziele ausgeführt? Lösen Abhängigkeiten reproduzierbar auf? Greifen Cache- oder Artefakt-Schritte auf die erwarteten Dateien zu? Ein grüner Build ohne die vorgesehenen Tests oder ohne das erwartete Ausgabe-Artefakt ist keine vollständige Migration.

Wenn ein Workflow Secrets verwendet, überprüfen Sie außerdem, ob sie nur den benötigten Jobs und Schritten zur Verfügung stehen. GitHub beschreibt den Umgang mit verschlüsselten Werten in der Dokumentation zu Actions-Secrets. Geben Sie sensible Inhalte weder in Diagnoseausgaben noch als unmaskierte Kommandozeilenwerte aus. Für Ihre Datenschutzprüfung gehört auch dazu, festzuhalten, welche Zugangsdaten in der CI-Umgebung verwendet werden und wer die Workflow-Konfiguration ändern darf.

Vor der Freigabe: Signierung, Archiv und Upload getrennt abnehmen

Ein erfolgreicher Build und ein erfolgreicher Release sind unterschiedliche Ergebnisse. Führen Sie deshalb in einem nicht produktiven Release-Lauf die Signierungs- und Exportstrecke aus, bevor der neue Runner eine reguläre Veröffentlichung übernimmt.

Prüfen Sie mindestens:

• Ob das vorgesehene Zertifikat und Provisioning Profile im Workflow verfügbar sind, ohne dass deren Inhalte im Protokoll offengelegt werden.
• Ob Xcode das Archiv für das gewünschte Ziel erzeugt und der Export mit den vorgesehenen Einstellungen abgeschlossen wird.
• Ob das ausgegebene IPA am erwarteten Pfad liegt und zum vorgesehenen Verteilungsweg passt.
• Ob ein Upload tatsächlich gestartet und von App Store Connect verarbeitet wird.

Apple beschreibt Archivierung, Export und Verteilung in der Dokumentation zur App-Verteilung an registrierte Geräte. Für die Prüfung des Uploads und des Verarbeitungsstatus ist Apples Anleitung zum Hochladen von Builds in App Store Connect maßgeblich. Bewerten Sie den Erfolg des Upload-Schritts nicht mit dem späteren Status in App Store Connect gleich: Das sind getrennte Stationen, die Sie auch getrennt dokumentieren sollten.

Prüfen Sie die IPA nicht nur darauf, ob eine Datei vorhanden ist. Stellen Sie sicher, dass die Datei aus dem erwarteten Archiv- und Exportprozess stammt und für den vorgesehenen Distributionsweg gedacht ist. Bei einer ungeklärten Signierungsabweichung sollten Sie nicht durch einen produktiven Upload „testen“: Beenden Sie den Lauf, sichern Sie die Protokolle und untersuchen Sie die Konfiguration in einer kontrollierten Umgebung.

Bei der Umschaltung: Freigabebedingungen und Rückfall festlegen

Vor dem Merge müssen alle erforderlichen Checks erfüllt sein. Definieren Sie die Freigabe so, dass ein Teammitglied anhand von Workflow-Läufen und Artefakten nachvollziehen kann, warum der Runner-Wechsel akzeptiert wurde. Verlassen Sie sich nicht auf ein einzelnes grünes Häkchen, wenn Signierung und Upload darin gar nicht enthalten waren.

Nutzen Sie diese Entscheidungszweige:

• Wenn Build und vorgesehene Tests erfolgreich sind, und die aktive Xcode-Auswahl samt SDK im Protokoll passt, dann kann der Runner für den nächsten kontrollierten Release-Lauf freigegeben werden.
• Wenn zusätzlich Archiv, Signierung und IPA-Export geprüft wurden und das Ergebnis dem vorgesehenen Verteilungsweg entspricht, dann kann der produktive Workflow umgestellt werden.
• Wenn ein benötigtes Werkzeug fehlt, ein Release-Artefakt nicht reproduzierbar ist oder der Uploadpfad ungeklärt bleibt, dann behalten Sie den bisherigen Runner für den produktiven Release bei.
• Wenn nach der Umschaltung ein kritischer Schritt ausfällt, dann stellen Sie die dokumentierte frühere Runner-Auswahl wieder her und untersuchen Sie den Fehler getrennt vom laufenden Release.

Setzen Sie den Rückfalltrigger vor dem Merge fest. Geeignete Auslöser sind ein reproduzierbarer Fehler bei der Signierung, ein nicht erwartungsgemäßes Export-Ergebnis oder eine fehlende Abhängigkeit, die den Release blockiert. Dokumentieren Sie dazu Commit, Workflow-Lauf und Fehlerausschnitt. So muss das Team im Störungsfall nicht erst rekonstruieren, welche Konfiguration vorher funktioniert hat.

Nach der Migration: Image-Änderungen nachvollziehbar verwalten

Speichern Sie mit der Änderung das verwendete Runner-Label, die geprüfte Xcode-Auswahl, die relevanten Workflow-Läufe und das Abnahmeergebnis. Halten Sie außerdem fest, welche Jobs Signierung und Export enthalten und an welcher Stelle der Rückfall erfolgt. Diese Aufzeichnungen erleichtern die nächste Prüfung und verhindern, dass ein späterer Image-Wechsel mit dem jetzigen Abnahmeergebnis verwechselt wird.

Wiederholen Sie die Prüfung, wenn GitHub die Runner-Image-Dokumentation ändert oder Apple eine neue Xcode-Version beziehungsweise neue Systemanforderungen veröffentlicht. Übernehmen Sie Änderungen nicht ungeprüft in Release-Workflows, nur weil ein Label weiterhin akzeptiert wird.

Für Teams, die CI-Secrets und Build-Artefakte verwalten, sollte die Wartungsnotiz auch die Zuständigkeit für Workflow-Änderungen und die Behandlung sensibler Daten benennen. Wenn Sie dabei die Umgebung und Zugriffswege Ihres Mac-Builds dokumentieren, können Sie ergänzend die Datenschutzinformationen von macworker prüfen.

Häufige Fragen zur Runner-Migration

Die folgenden Fragen ergänzen die Abnahme: Sie betreffen vor allem die Änderung des Runner-Labels, die Austauschbarkeit des alten Images sowie die Prüfung von Signierung, IPA und Rückfall. Die Antworten ersetzen nicht den Test im eigenen Workflow, sondern zeigen, welche Entscheidung Sie anhand der Ergebnisse treffen sollten.

Wie wechseln Sie in GitHub Actions zum Xcode-27-Runner?

Ändern Sie runs-on zuerst ausschließlich in einem separaten Branch. Übernehmen Sie das aktuell dokumentierte Runner-Label aus der GitHub-Image-Beschreibung, prüfen Sie im Laufprotokoll Xcode und SDK und testen Sie danach Build, Signierung und Export. Erst wenn das erwartete Artefakt vorliegt und die frühere Konfiguration wieder aktiviert werden kann, sollte der produktive Workflow folgen.

Ist der Xcode-27-Runner ein direkter Ersatz für den bisherigen macOS-Runner?

Nicht automatisch. Runner-Label und Image-Inhalt müssen zu den Skripten, Werkzeugen, Abhängigkeiten und Signierungsschritten Ihres Projekts passen. Kontrollieren Sie insbesondere fest codierte Pfade und vorausgesetzte Programme. Kann der neue Runner ein benötigtes Release-Ergebnis nicht reproduzieren, lassen Sie den bisherigen Runner zunächst als Rückfallziel bestehen.

Wie prüfen Sie Signierung und IPA nach dem Wechsel?

Führen Sie einen nicht produktiven Release-Lauf aus. Verifizieren Sie, dass Zertifikat und Provisioning Profile verfügbar sind, das Archiv exportiert wird und das IPA dem vorgesehenen Distributionsweg entspricht. Prüfen Sie den Upload danach getrennt vom Build und vom Status in App Store Connect. Dokumentieren Sie die einzelnen Ergebnisse, statt einen erfolgreichen Build mit einem abgeschlossenen Upload gleichzusetzen.

Wie stellen Sie den alten Runner wieder her, wenn der Build scheitert?

Nutzen Sie die vor dem Test gesicherte Runner-Auswahl und aktivieren Sie sie, sobald ein kritischer Build-, Signierungs- oder Exportschritt nicht zuverlässig funktioniert. Erfassen Sie den fehlgeschlagenen Lauf und vergleichen Sie die Protokolle, bevor Sie weitere Änderungen vornehmen. Wenn Sie Runner, Abhängigkeiten und Skripte gleichzeitig ändern, wird die Fehlersuche unnötig mehrdeutig.

Wenn der Build dauerhaft laufen muss: CI und Mac-Umgebung vergleichen

Ein von GitHub gehosteter Runner ist praktisch, wenn Ihr Workflow sauber automatisiert ist und die Umgebung über die dokumentierte Runner-Auswahl genügt. Grenzen zeigen sich, wenn Sie einen Zustand dauerhaft erhalten, Werkzeuge selbst verwalten oder einen Build außerhalb des bestehenden Actions-Ablaufs untersuchen müssen. Bei gehosteten Runnern sollten Sie daher die Eigenschaften des Dienstes und die Image-Änderungen mit den eigenen Anforderungen abgleichen; GitHub erläutert Plattformen und Architekturen in der Dokumentation zu gehosteten Runnern.

Eine gemietete Mac-Umgebung ist nicht für jedes Projekt die bessere Wahl. Sie erfordert weiterhin Pflege der Build-Umgebung und löst keine fehlerhaften Abhängigkeiten oder unsicheren Release-Skripte. Wenn Sie jedoch eine zugängliche macOS-Umgebung für wiederholbare Builds, manuelle Prüfungen oder Tests neben der bestehenden CI benötigen, kann macworker eine passende Ergänzung sein. Über Mietpläne für Mac-Umgebungen können Sie prüfen, ob ein zeitlich begrenzter Zugang besser zu Ihrem Vorhaben passt. Für den Zugriff per Browser finden Sie außerdem Informationen zur noVNC-Verbindung.

Treffen Sie die Entscheidung anhand des tatsächlichen Betriebs: Wenn Ihre Builds vollständig automatisiert sind und der gehostete Runner reproduzierbare Ergebnisse liefert, brauchen Sie möglicherweise keine zusätzliche Umgebung. Wenn dagegen wechselnde Image-Inhalte, begrenzte Kontrolle über den Build-Zustand oder aufwendige manuelle Nachprüfungen Ihren Release-Prozess erschweren, kann ein separat zugänglicher Mac die Abläufe ergänzen. Schließen Sie die Migration erst ab, wenn die Migration des GitHub Actions Xcode 27 Runners mit überprüfter Toolchain, erfolgreicher Signierung, erwartetem Artefakt und dokumentiertem Rückfallweg belegt ist.

Häufig gestellte Fragen