Homebrew 7 GitHub Actions-Fehler migrieren? Leitfaden 2026

Die Veröffentlichung von Homebrew 7.0.0 bestätigt die entscheidende Änderung: Referenzen auf Homebrew/actions/*@master wurden entfernt. Verlassen Sie sich nicht länger darauf. Wechseln Sie entsprechend der offiziellen Migrationsempfehlung zu einem CalVer-Release oder einem vollständigen SHA und testen Sie die Änderung isoliert in Ihrer macOS-CI. Ein bloßer Wechsel zu @main ist keine langfristige Versionsfixierung.

Zuletzt aktualisiert am 16.11.2026; geprüft anhand der Homebrew-7.0.0-Ankündigung, der offiziellen Migrationsaufzeichnung und des Homebrew/actions-Repositories.

Dieser Leitfaden richtet sich an Maintainer von Homebrew-Formeln, Casks und abhängigen Projekten, deren Workflows auf alte Branch-Referenzen zeigen.
Er hilft Ihnen, Action-Versionen in macOS-CI gezielt zu prüfen, statt einen fehlgeschlagenen Lauf vorschnell als Netzwerkproblem einzustufen.
Wenn Sie CI/CD für mehrere Repositories verantworten, erhalten Sie außerdem eine überprüfbare Versions- und Rückfallstrategie.

01 Vor der Änderung: Fehlerursache und Reichweite feststellen

Die offizielle Homebrew-7.0.0-Mitteilung hält fest, dass Referenzen auf Homebrew/actions/*@master entfernt wurden. Die Migrationsaufzeichnung dokumentiert die Änderung im Actions-Projekt. Das ist kein Signal, dass ein Lauf nach einem temporären Wiederholungsversuch zuverlässig wieder funktionieren wird: Die Referenz selbst muss ersetzt werden. Ankündigung zu Homebrew 7.0.0 und Änderungsnachweis zur Migration sind die maßgeblichen Stellen für diese Aussage.

Warum schlägt @master nach Homebrew 7 fehl? Weil eine Action-Referenz auf einen konkreten Ref-Namen zeigt. Wenn der verwendete Ref entfernt wurde, macht GitHub Actions daraus nicht automatisch einen Verweis auf einen neuen Tag oder einen anderen Branch. Die Workflow-Syntax beschreibt, wie Actions über Repository und Ref eingebunden werden. Prüfen Sie deshalb die tatsächlich aufgelöste Referenz, statt aus einem fehlgeschlagenen Lauf auf einen vorübergehenden Transportfehler zu schließen. Die GitHub-Dokumentation zur Workflow-Syntax erläutert die Form solcher Verweise.

Auch @main sollten Sie getrennt beurteilen. Homebrew führt diese Referenz als Migrationsempfehlung auf, aber ein beweglicher Branch benennt nicht unveränderlich den geprüften Code. Ein erfolgreicher Lauf mit @main kann eine notwendige Zwischenstation sein; er ersetzt keine teamseitige Entscheidung zur Versionsfixierung. Unterscheiden Sie daher zwischen einer aktuell akzeptierten Referenz und einer kontrolliert freigegebenen Version.

Bestandsaufnahme vor dem ersten Commit

Suchen Sie nicht nur in den sichtbaren Workflow-Dateien. Action-Verweise können in wiederverwendbaren Workflows, zusammengesetzten Actions oder Hilfsskripten liegen. Notieren Sie für jeden Fund den Pfad, die Action, den verwendeten Ref, den Zweck und die nachgelagerten Schritte. So erkennen Sie, welche Änderung nur eine einzelne Jobzeile betrifft und welche andere Ausgaben oder Abhängigkeiten berühren könnte.

Sie können die Repository-Suche oder eine lokale Textsuche verwenden. Passen Sie den Suchpfad an Ihre Verzeichnisstruktur an:

grep -RInE 'Homebrew/actions/[^[:space:]@]+@(master|main)' .github scripts

Behandeln Sie das Ergebnis als Suchhilfe, nicht als vollständigen Beweis. Prüfen Sie zusätzlich wiederverwendbare Workflows und Dateien außerhalb der angegebenen Verzeichnisse. Eine gefundene Zeile kann beispielsweise in einem anderen Workflow wiederverwendet oder in einem Skript dynamisch zusammengesetzt werden. Kontrollieren Sie auch, ob ein Workflow über workflow_call eingebunden wird und deshalb nicht direkt über den üblichen Pull-Request-Pfad läuft.

Halten Sie pro Fund mindestens diese Angaben fest:

  • Datei und Job: Wo wird die Action aufgerufen, und in welchem Job läuft sie?
  • Zweck: Welche Aufgabe übernimmt sie im Ablauf?
  • Eingaben und Ausgaben: Welche Parameter werden übergeben und welche Ergebnisse später gelesen?
  • Abhängigkeiten: Welche Schritte laufen davor und danach?
  • Aktueller Ref: Ist es der entfernte @master-Ref, die bewegliche @main-Referenz oder bereits eine feste Version?
  • Verantwortung: Wer kann die Änderung prüfen und wer gibt den Workflow für den produktiven Einsatz frei?

Diese Liste macht Ihre Änderung prüfbar und senkt das Risiko, nur den ersten Treffer zu reparieren. Beziehen Sie auch Workflows ein, die erst bei Freigabe, geplantem Lauf oder manuellem Start ausgeführt werden. Die Repository-Suche ersetzt nicht die Prüfung der tatsächlich verwendeten Workflow-Dateien.

02 Versionswahl: CalVer-Release oder vollständiger SHA

Es gibt nicht für jedes Team eine einzige richtige Wahl. Entscheidend ist, ob Ihre Aktualisierungs- und Sicherheitsprüfung CalVer-Releases nachvollziehbar verwalten kann oder ob Sie Änderungen an Action-Code nur nach gezielter Commit-Prüfung freigeben möchten. Maßgeblich sind die im offiziellen Homebrew/actions-Repository aktuell dokumentierten Releases und die von Homebrew festgelegte Migrationsrichtung. Prüfen Sie dort die verfügbaren Tags, bevor Sie eine Referenz in einen Workflow übernehmen.

Sollten Sie CalVer oder einen vollständigen SHA verwenden? Wählen Sie CalVer, wenn Ihr Team geprüfte Release-Tags in einem wiederkehrenden Aktualisierungsprozess verfolgen kann. Wählen Sie einen vollständigen SHA, wenn Sie den exakt geprüften Commit festschreiben und Änderungen explizit über einen Review einspielen wollen. Vergleichen Sie bei beiden Varianten nicht nur den Namen der Referenz, sondern auch den Upstream-Stand, den Sie tatsächlich freigeben.

  • CalVer-Release: Der Ref bezeichnet eine veröffentlichte Version. Das erleichtert die Lesbarkeit und die regelmäßige Prüfung auf neue Releases. Dafür muss Ihr Team festlegen, wer Updates beobachtet, sie testet und nach dem Review einträgt. Ein Tag allein ist nicht automatisch eine Sicherheitsprüfung.
  • Vollständiger SHA: Der Ref bindet den Workflow an einen konkreten Commit. Das macht die Auswahl des ausgeführten Codes überprüfbarer und begrenzt unbeabsichtigte Änderungen durch bewegliche Branches. Es erhöht aber den Pflegeaufwand: Aktualisierungen erfordern einen bewussten Ref-Wechsel und eine erneute Abnahme.
  • @main als Übergang: Ein Branch kann helfen, eine Migration zu testen, wenn die offizielle Empfehlung darauf verweist. Da sich der Inhalt eines Branches weiterentwickeln kann, sollten Sie den Übergang dokumentieren und eine feste Version als Ziel festlegen.

GitHub beschreibt sowohl den sicheren Umgang mit Action-Abhängigkeiten als auch die Bedeutung fester Referenzen in der Dokumentation zur sicheren Verwendung von Actions. Für Teams, die Abhängigkeiten systematisch prüfen und aktualisieren, ist auch die GitHub-Dokumentation zu Workflow-Abhängigkeits-Lockdateien relevant. Übernehmen Sie die dort beschriebenen Verfahren nur, wenn sie zu Ihrem Repository und Ihrer Richtlinie passen. Eine Dokumentation ersetzt nicht die Bestätigung, dass eine konkrete Homebrew-Action den gewünschten Ref tatsächlich anbietet.

Entscheidungshilfe für die Ref-Auswahl

Verwenden Sie die folgenden Bedingungen als verbindliche Auswahlhilfe. Tragen Sie die gewählte Option in Ihrer Migrationsliste ein, damit Reviewer erkennen, warum ein Ref verwendet wird.

  • Wenn Ihr Team veröffentlichte CalVer-Tags regelmäßig bewertet und kontrolliert aktualisiert, dann verwenden Sie ein verfügbares CalVer-Release und halten Sie den Aktualisierungsreview fest.
  • Wenn Sie den geprüften Action-Code bis zu einer expliziten Freigabe unverändert nutzen müssen, dann pinnen Sie den vollständigen SHA des verifizierten Commits.
  • Wenn die Action im offiziellen Repository keinen passenden Release-Tag oder keinen für Sie nachvollziehbaren Commit bietet, dann übernehmen Sie keinen geratenen Ref. Prüfen Sie die aktuelle Upstream-Dokumentation und verschieben Sie die Freigabe, bis eine belastbare Referenz vorliegt.
  • Wenn Ihr Repository bewegliche Referenzen durch eine Richtlinie einschränkt, dann gleichen Sie die gewählte Form mit den Repository-Einstellungen ab. GitHub dokumentiert die verfügbaren Optionen unter Einstellungen zur Fixierung von Actions.
  • Wenn eine schnelle Wiederherstellung nötig ist, dann trennen Sie die temporäre Reparatur vom späteren Update- und Sicherheitsprozess. Ein kurzfristig erfolgreicher Lauf ist noch keine dauerhafte Freigabe.

Achtung: Verwenden Sie @main nicht als stillschweigenden Ersatz für eine freigegebene Version. Wenn Sie es kurzfristig zum Wiederherstellen eines Tests benötigen, kennzeichnen Sie es als Übergang, dokumentieren Sie die verantwortliche Person und setzen Sie einen konkreten Prüftermin für die dauerhafte Referenz.

03 Isolierte Migration: Referenzen ersetzen und Verträge prüfen

Erstellen Sie einen separaten Branch, bevor Sie die erste Referenz ändern. Damit können Sie Änderungen im Pull Request prüfen, den Testlauf eindeutig zuordnen und bei einem Fehlschlag den stabilen Workflow unverändert lassen. Ändern Sie nicht mehrere unabhängige Action-Versionen gleichzeitig, wenn sich deren Fehlerursachen später nicht mehr auseinanderhalten lassen.

Ersetzen Sie die Einträge aus Ihrer Bestandsaufnahme einzeln. Das Beispiel zeigt bewusst Platzhalter. Es behauptet weder, dass eine bestimmte Action diesen Namen trägt, noch, dass der dargestellte SHA oder Tag für ein konkretes Projekt verfügbar ist:

steps:
  - name: Platzhalter für eine Homebrew-Action
    uses: Homebrew/actions/<ACTION>@<CALVER-RELEASE-ODER-VOLLSTAENDIGER-SHA>
    with:
      <EINGABE>: <WERT>

Den tatsächlichen Action-Namen, Ref und Eingaben müssen Sie anhand des offiziellen Repositories und Ihres eigenen Workflows einsetzen. Kopieren Sie keine Beispielwerte ungeprüft in einen produktiven Workflow. Die Dokumentation zur GitHub-Workflow-Syntax beschreibt, wie uses und with im Workflow zusammenwirken. Maßgeblich für die unterstützten Eingaben bleibt die Dokumentation der jeweiligen Action.

Prüfen Sie danach den Workflow-Vertrag, nicht nur die Zeile mit uses:

  1. Eingaben: Stimmen Namen, Pflichtfelder und übergebene Werte mit der Action-Version überein? Vergleichen Sie die tatsächlich eingesetzten Werte mit der Dokumentation und dem bisherigen Workflow.
  2. Ausgaben: Lesen nachfolgende Schritte weiterhin die erwarteten Outputs? Ändern Sie keine Output-Referenz allein aufgrund einer Vermutung. Wenn die Action selbst keine benötigte Ausgabe mehr liefert, dokumentieren Sie, welcher Schritt davon betroffen ist.
  3. Berechtigungen: Sind die dem Job eingeräumten Rechte für die Aufgabe weiterhin erforderlich und passend? Bewahren Sie keine übermäßig breiten Rechte nur deshalb, weil sie im alten Workflow standen. Die GitHub-Empfehlungen zur sicheren Nutzung von Actions bieten den Rahmen für diese Prüfung.
  4. Reihenfolge: Werden Checkout, Umgebungsaufbau und Action-Aufruf in der Reihenfolge ausgeführt, die der Arbeitsablauf voraussetzt? Achten Sie auf Umgebungsvariablen und Dateien, die ein früherer Schritt bereitstellt.
  5. Folgeschritte: Nutzen Build-, Test- oder Veröffentlichungsbefehle tatsächlich die Ergebnisse der migrierten Action? Ein erfolgreicher Action-Schritt reicht nicht, wenn ein späterer Schritt mit veralteten Annahmen arbeitet.
  6. Änderungsumfang: Sind nur die geplanten Referenzen und dazugehörige notwendige Workflow-Anpassungen geändert worden? Trennen Sie unabhängige Bereinigungen vom Migrations-Commit.

Vergleichen Sie den Diff mit Ihrer ursprünglichen Liste. Jede geänderte Referenz sollte einem Fund zugeordnet sein. Unerklärte Änderungen an Workflow-Parametern oder Berechtigungen gehören in einen gesonderten Review, damit die Migration nicht nebenbei neue Verhaltensänderungen einführt. Nutzen Sie den Pull Request außerdem, um die Begründung für CalVer oder SHA festzuhalten. Das erspart späteren Maintainerinnen und Maintainern die erneute Rekonstruktion Ihrer Entscheidung.

04 Abnahme in macOS-CI: vom Ref bis zum reproduzierbaren Ergebnis

Führen Sie den ersten Test in einer isolierten macOS-CI-Ausführung aus, die dem Zielworkflow so nahe wie nötig kommt. Ein syntaktisch gültiger Workflow beweist noch nicht, dass die Action aufgelöst wird, dass Eingaben akzeptiert werden oder dass das Ergebnis für den folgenden Build genügt. Halten Sie Runner, Betriebssystem, Workflow-Commit und relevante Laufprotokolle fest. Behaupten Sie keine allgemeine Kompatibilität auf Basis eines einzelnen Laufs.

Wenn Ihnen ein geeigneter Mac für diese Prüfung fehlt, lesen Sie zunächst den Überblick zu CALMVPS und den verfügbaren Mac-Optionen. Entscheiden Sie erst danach, ob eine gemietete Umgebung für den isolierten Test zu Ihrem Ablauf passt. Prüfen Sie Verfügbarkeit und Konditionen auf der CALMVPS-Preisseite, bevor Sie dafür planen.

Arbeiten Sie die Abnahme in dieser Reihenfolge durch:

  1. Referenzauflösung: Startet der Job, und wird die gewählte Action-Referenz erfolgreich aufgelöst? Prüfen Sie die Logzeile, die den verwendeten Ref erkennen lässt.
  2. Action-Ausführung: Erreicht der Workflow den Schritt, und endet dieser ohne einen Eingabe-, Berechtigungs- oder Auflösungsfehler?
  3. Ausgaben: Werden die von nachfolgenden Schritten erwarteten Werte erzeugt und gelesen? Prüfen Sie nicht nur, ob der Action-Schritt erfolgreich endet.
  4. Homebrew-Aufgabe: Erledigt der Workflow die vorgesehene Aufgabe tatsächlich? Lassen Sie den für Ihr Projekt relevanten Build oder Test folgen, statt die Action isoliert als Endergebnis zu behandeln.
  5. Wiederholbarkeit: Führen Sie den Ablauf unter denselben dokumentierten Bedingungen erneut aus. Vergleichen Sie Protokolle und Ergebnisartefakte, um nicht einen einmaligen Erfolg mit reproduzierbarer CI gleichzusetzen.
  6. Änderungsnachweis: Verknüpfen Sie den Lauf mit Workflow-Commit, Ref, Runner und Systemangabe. So erkennen Reviewer später, was konkret geprüft wurde.

Welche Ergebnisse müssen nach der Migration belegt sein? Mindestens die Auflösung der neuen Referenz, die Annahme der benötigten Eingaben, die korrekte Weitergabe relevanter Ausgaben und ein erfolgreicher Lauf der eigentlichen Homebrew-Aufgabe. Ergänzen Sie projektspezifische Tests, wenn die Action ein Artefakt erzeugt, auf das spätere Schritte angewiesen sind. Ein erfolgreicher Action-Schritt ohne bestätigten Folgeschritt ist eine unvollständige Abnahme.

Halten Sie die Abnahmeergebnisse in einer für Ihr Team lesbaren Form fest. Ein kurzer Kommentar im Pull Request kann den Ref, den verwendeten Runner, den Workflow-Commit und das Ergebnis der relevanten Folgeaufgabe nennen. Speichern Sie keine Zugangsdaten, Tokens oder vertraulichen Umgebungswerte in dieser Dokumentation. Prüfen Sie vor dem Teilen von Logs, ob diese vertrauliche Pfade oder Informationen enthalten, die nicht in einen öffentlich sichtbaren Pull Request gehören.

Erinnerung: Ein erfolgreicher Lauf belegt das Ergebnis dieses konkreten Workflow-Commits in der aufgezeichneten Umgebung. Er belegt weder die Eignung jedes macOS-Systems noch die Sicherheit zukünftiger Ref-Änderungen. Bewahren Sie deshalb die Testbedingungen gemeinsam mit dem Review auf.

05 Kontrollierte Freigabe und Rückfall

Geben Sie die Änderung erst frei, wenn die Abnahme die tatsächlich verwendete Referenz und das erwartete Projektergebnis abdeckt. Vergleichen Sie die neuen Laufprotokolle mit dem letzten bekannten erfolgreichen Stand. Achten Sie auf Unterschiede bei Eingaben, Ausgaben und nachfolgenden Schritten. Ein reiner Statusvergleich „rot zu grün“ sagt nicht, ob der Workflow noch dasselbe erledigt.

Legen Sie vor dem Merge fest, was bei einem Fehlschlag passiert. Der Rückfall soll auf eine bereits überprüfte Referenz zeigen, nicht auf den entfernten @master-Ref. Bewahren Sie den vorherigen Workflow-Commit und die Abnahmedaten auf. Benennen Sie im Review die Person oder Rolle, die über Rückfall und erneute Freigabe entscheidet. Wenn mehrere Repositories betroffen sind, migrieren Sie sie in kontrollierten Gruppen und lassen Sie nach jeder Gruppe die vereinbarten Prüfergebnisse einsehen.

Definieren Sie außerdem, wodurch eine erneute Prüfung ausgelöst wird: etwa ein neuer offizieller Action-Release, eine relevante Änderung im Homebrew-Migrationshinweis oder eine Aktualisierung der Repository-Richtlinie. Prüfen Sie vor jedem Ref-Update dessen Verfügbarkeit im offiziellen Repository und wiederholen Sie die betroffenen Tests. Legen Sie die Intervalle nicht pauschal fest, sondern so, dass Ihr Team die Prüfung tatsächlich verantworten kann.

Für die Freigabe kann diese abhakbare Liste im Pull Request stehen:

  • [ ] Alle Vorkommen von Homebrew/actions/*@master und die zu prüfenden @main-Referenzen sind erfasst.
  • [ ] Für jede betroffene Action ist der gewählte CalVer-Tag oder vollständige SHA anhand des offiziellen Repositories geprüft.
  • [ ] Eingaben, Ausgaben, Berechtigungen und Reihenfolge der betroffenen Workflow-Schritte sind geprüft.
  • [ ] Der Testlauf dokumentiert Workflow-Commit, Ref und macOS-Runner.
  • [ ] Die nachgelagerte Homebrew-Aufgabe wurde ausgeführt und ihr Ergebnis geprüft.
  • [ ] Der Rückfallweg verweist auf eine bestätigte Version und hat eine verantwortliche Person.
  • [ ] Ein Auslöser für die nächste Versionsprüfung ist festgehalten.

Wenn ein Punkt offenbleibt, markieren Sie die Änderung als nicht abgenommen. Bei einem reinen Ref-Auflösungsfehler beheben Sie zunächst die Referenz. Bei einem Fehler in Eingaben oder Outputs vergleichen Sie die Action-Dokumentation und den Workflow-Vertrag. Bei einem nachgelagerten Buildfehler prüfen Sie, ob die Migration tatsächlich die Ursache ist, bevor Sie den Ref zurücksetzen. Diese Einordnung verhindert, dass ein unabhängiger Projektfehler als Beleg gegen den neuen Ref behandelt wird.

macOS-CI verdient besondere Aufmerksamkeit, weil ein Linux-Job die Ausführung auf einem Mac nicht ersetzen kann, wenn die Arbeitslast die macOS-Umgebung voraussetzt. Gleichzeitig ist ein gemieteter Mac nicht automatisch die richtige Lösung für jedes Team: Wer bereits einen verlässlich verwalteten Mac-Runner hat, sollte zuerst diesen für die Abnahme nutzen. Wer dagegen für eine zeitlich begrenzte Migration keinen geeigneten Testknoten bereitstellen kann, kann eine Remote-Mac-Option gegen den Aufwand für Beschaffung, Betrieb und Zugriffskontrolle abwägen.

Berücksichtigen Sie dabei auch, welche Quelltexte und Zugangsdaten auf dem Knoten liegen und welche Datenschutz- und Sicherheitsvorgaben für Ihr Projekt gelten. Ein Remote-Knoten ist nur dann sinnvoll, wenn der Zugriff kontrolliert ist, Logs und Zugangsdaten angemessen behandelt werden und Ihr Team die erforderliche Umgebung tatsächlich testen kann. Für dauerhaft ausgelastete, stabile Workloads oder Aufgaben mit erforderlichen physischen Schnittstellen ist eine gemietete Umgebung nicht zwingend sinnvoll.

Eine vorhandene Linux-CI kann Verwaltungsaufwand sparen, löst aber keine macOS-spezifische Abnahme. Ein lokal geteilter Mac kann wiederum durch konkurrierende Jobs, wechselnde Arbeitsstände und unklare Zuständigkeit schwerer reproduzierbar sein. Für eine kurze, isolierte Verifikation kann ein Remote-Mac-Testknoten die Beschaffung eigener Hardware vermeiden; für dauerhaft hohe Auslastung kann ein eigener, zuverlässig verwalteter Mac wirtschaftlicher oder einfacher zu kontrollieren sein. Entscheiden Sie anhand Ihrer tatsächlichen Runner-Lücke, nicht allein wegen eines einzelnen fehlgeschlagenen Laufs.

Wenn Ihnen eine kontrollierte Mac-Umgebung für den Migrationstest fehlt, prüfen Sie die CALMVPS-Optionen erst nach der Workflow-Bestandsaufnahme und legen Sie vorab fest, welche Tests dort laufen sollen. Führen Sie die isolierte Abnahme aus, dokumentieren Sie Ref und Ergebnis und entscheiden Sie anschließend, ob der Knoten nur für die Migration oder auch für wiederkehrende CI-Prüfungen geeignet ist. Steht Ihnen bereits ein passender Mac zur Verfügung oder benötigen Sie für Ihre Arbeit zwingend lokale physische Schnittstellen, nutzen Sie diese vorhandene Lösung. Andernfalls kann CALMVPS eine flexible Möglichkeit sein, die Migration in einer echten macOS-Umgebung zu verifizieren, ohne dafür zuerst eigene Mac-Hardware anzuschaffen.