Ne conservez pas les références Homebrew/actions/*@master : Homebrew 7.0.0 indique qu’elles ont été supprimées et recommande de migrer vers une version CalVer ou un SHA complet. Effectuez le changement dans une branche isolée, puis vérifiez la résolution de l’action, ses entrées et sorties ainsi que le résultat réel de la tâche sur votre CI macOS. Remplacer seulement @master par @main ne constitue pas une stratégie durable de fixation.
Ce guide s’adresse aux mainteneurs de formules Homebrew, de casks et de projets qui doivent réparer des workflows utilisant une ancienne référence.
Il est également destiné aux ingénieurs responsables de CI macOS qui doivent valider une mise à jour sans perturber les autres tâches.
Les responsables de plateformes de développement y trouveront des critères pour rendre les versions contrôlables et réversibles.
Dernière mise à jour : 16 novembre 2026. Les changements cités ont été vérifiés à partir de l’annonce Homebrew 7.0.0, du guide de migration et du dépôt officiel Homebrew/actions. Vérifiez de nouveau ces sources avant fusion : les versions publiées et les consignes peuvent évoluer.
01 Avant de modifier le workflow, établissez la cause
Une erreur de résolution d’action n’est pas nécessairement un incident réseau. Une référence GitHub Actions telle que organisation/depot/action@ref demande à GitHub de résoudre précisément ref. Si la branche ou le tag n’existe plus, le workflow ne peut pas poursuivre à partir de cette référence. GitHub ne prévoit pas de redirection automatique d’un ancien nom de branche vers un nouveau. La syntaxe officielle des workflows et des actions permet de vérifier la forme de chaque référence.
Homebrew confirme dans son annonce de version 7.0.0 la suppression des références Homebrew/actions/*@master. La demande de migration dans le dépôt Homebrew/actions apporte le contexte de cette transition. Il faut distinguer deux cas : @master est la référence supprimée signalée par l’annonce ; @main figure parmi les références qu’il est recommandé de migrer. Le second cas ne signifie pas que toutes les exécutions de @main échouent déjà, mais qu’il vaut mieux ne pas le retenir comme point fixe de long terme.
Avant toute modification, repérez l’échec exact dans les journaux. Une erreur de résolution de référence appelle une migration du uses: concerné. Une action qui se résout, mais échoue ensuite sur une entrée ou une commande, demande plutôt un diagnostic de son exécution. Changer plusieurs éléments à la fois brouille la cause : conservez donc le commit de départ et notez le premier message d’erreur reproductible.
Inventaire des références à examiner
Ne limitez pas la recherche au fichier de workflow qui a échoué. Une action peut être appelée depuis un autre workflow, un workflow réutilisable ou un script qui génère des fichiers. Recherchez les deux formes de branche, puis consignez le chemin et le rôle de chaque référence.
grep -RInE 'Homebrew/actions/[^[:space:]]+@(master|main)' .github scripts
Cette commande est un point de départ : adaptez les chemins aux répertoires utilisés par votre dépôt. Vérifiez également les workflows appelés par workflow_call et les fichiers générés, s’il y en a. L’inventaire officiel des actions Homebrew vous aide à confirmer le nom de l’action et les références effectivement publiées. N’inférez pas l’existence d’un tag à partir d’un ancien exemple copié dans un autre projet.
Pour chaque occurrence, notez l’action, sa fonction, les étapes en amont et les étapes qui consomment ses sorties. Cette dépendance est importante : une action peut réussir seule tandis qu’une étape ultérieure échoue parce qu’elle reçoit une valeur différente, ou parce qu’elle n’en reçoit plus du tout.
| Élément de l’inventaire | À relever | Pourquoi le noter |
|---|---|---|
| Référence actuelle | Fichier, ligne et uses: exact |
Distinguer une référence @master supprimée d’une référence @main à faire migrer |
| Fonction de l’action | Préparation, test, publication ou autre rôle | Évaluer le périmètre touché par la mise à jour |
| Contrat d’exécution | Entrées, sorties et variables utilisées | Repérer les conséquences en aval |
| Environnement | Système macOS et type de runner du workflow | Reproduire le contexte de validation |
| Retour arrière | Référence précédemment validée et commit associé | Restaurer un état connu si le test échoue |
02 Préparez une migration contrôlable
Ne remplacez pas toutes les références par la même valeur sans examiner les exigences de votre équipe. Le choix entre une version CalVer et un SHA complet porte sur la manière dont vous suivez les changements, les examinez et les mettez à jour. La documentation GitHub sur l’usage sécurisé des actions explique les enjeux des références de dépendances et de leur fixation.
| Mode de référence | Atout pour l’équipe | Point de vigilance | À retenir si… |
|---|---|---|---|
| Version CalVer publiée | Lisible dans le diff et reliée à une version publiée que vous pouvez examiner | Vous devez surveiller les publications et décider quand les adopter | Votre équipe suit les versions et dispose d’une revue régulière |
| SHA complet | Désigne un commit précis, utile pour reproduire et auditer l’exécution | Moins lisible ; il faut documenter le changement et organiser les mises à jour | La politique exige une dépendance figée et une approbation explicite |
@main |
Peut aider à confirmer temporairement qu’une modification de branche répond au diagnostic | La branche peut avancer ; la référence n’assure pas un état stable | Vous effectuez une investigation temporaire, avec remplacement planifié |
Les noms de tags et les versions disponibles sont susceptibles de changer. Consultez le dépôt officiel Homebrew/actions avant de choisir une CalVer, puis vérifiez que la référence ciblée correspond bien à l’action concernée. Pour un SHA, copiez le commit complet depuis une source officielle et relisez-le : ne remplacez pas la valeur par un identifiant raccourci ou supposé.
La fixation d’une référence ne remplace pas la revue du code exécuté. GitHub documente aussi les fichiers de verrouillage des dépendances de workflows et les paramètres de politique de fixation des actions d’un dépôt. Vérifiez ces contrôles avec la politique de votre organisation : un workflow peut être techniquement corrigé mais rester incompatible avec les règles d’autorisation du dépôt.
Branche de migration
Créez une branche dédiée et gardez la modification aussi étroite que possible. Pour chaque ligne touchée, remplacez la référence par une version CalVer ou un SHA complet que vous avez vérifié. Utilisez des valeurs de remplacement dans les exemples de documentation ou les modèles partagés, plutôt que de présenter un nom de dépôt ou un SHA isolé comme une configuration valable partout.
steps:
- name: Exécuter une action Homebrew
uses: Homebrew/actions/<ACTION>@<CALVER_OU_SHA_COMPLET>
with:
<ENTREE_ATTENDUE>: <VALEUR_DU_PROJET>
Le nom d’organisation, le dépôt, le nom de l’action, les entrées et la référence ci-dessus sont des champs à remplacer. Comparez la déclaration with: à celle de la version publiée retenue. Vérifiez également les sorties lues par les étapes suivantes, les variables d’environnement et les permissions requises. Une version différente peut conserver le même nom d’action sans satisfaire les hypothèses particulières de votre projet.
03 Décidez selon votre processus de mise à jour
Utilisez ces conditions pour choisir une référence que l’équipe peut maintenir, pas seulement une valeur qui fait disparaître le message d’erreur.
- Si votre équipe suit chaque publication et peut examiner puis intégrer les mises à jour, choisissez une version CalVer disponible dans le dépôt officiel. Notez la date de la revue et prévoyez une nouvelle vérification au prochain changement pertinent.
- Si votre politique exige une référence immuable, choisissez le SHA complet d’un commit vérifié. Faites examiner le commit et conservez un lien vers sa provenance dans la demande de fusion.
- Si vous avez besoin de tester rapidement une correction non encore adoptée,
@mainpeut servir à isoler le diagnostic, mais revenez ensuite à une CalVer ou à un SHA complet avant de traiter la migration comme terminée. - Si la référence choisie n’existe pas ou si son contrat d’entrées est incertain, ne fusionnez pas. Revenez à l’inventaire, vérifiez les informations publiées dans le dépôt et obtenez une preuve de résolution sur la branche isolée.
- Si vous ne pouvez pas reproduire l’environnement du workflow, différez le déploiement. Préparez d’abord un essai sur un environnement macOS correspondant aux besoins du projet, ou réduisez le test à une étape isolée qui ne touche ni aux secrets ni à la publication.
Cette décision sépare la correction immédiate de la politique de maintenance. La première consiste à remplacer une référence supprimée ; la seconde définit comment votre équipe examinera les prochaines modifications. Si la CI exécute un travail sensible, relisez aussi les permissions et les secrets accessibles à l’action, conformément aux recommandations de sécurité GitHub citées plus haut.
04 Questions fréquentes sur la migration
Pourquoi @master cesse-t-il de fonctionner ?
L’annonce Homebrew 7.0.0 indique que les références Homebrew/actions/*@master ont été supprimées. GitHub Actions ne convertit pas automatiquement cette ancienne référence en @main ou en une version publiée. Relevez d’abord l’action et la ligne qui échouent, puis vérifiez les références disponibles dans le dépôt officiel avant de modifier le workflow.
CalVer ou SHA complet : que choisir ?
Une CalVer convient à une équipe qui suit les versions publiées et intègre les mises à jour après revue. Un SHA complet convient à une politique qui exige de fixer chaque dépendance sur un commit précis. Dans les deux cas, confirmez que la référence est présente dans le dépôt officiel et que l’action conserve les entrées et sorties dont dépend votre workflow.
Le remplacement par @main règle-t-il le problème durablement ?
Non. Homebrew inclut @main parmi les références à migrer ; cette branche peut évoluer sans changement dans votre fichier. Elle peut aider au diagnostic, mais ne doit pas devenir votre mécanisme permanent de fixation. Une fois la résolution testée, adoptez une CalVer ou un SHA complet, puis faites approuver le changement selon les règles de votre dépôt.
Que faut-il valider après le changement ?
Vérifiez que l’action se résout et démarre, que les entrées déclarées sont acceptées et que les sorties attendues sont disponibles pour les étapes suivantes. Exécutez ensuite la tâche Homebrew visée dans l’environnement macOS cible et comparez son résultat aux preuves de référence. Conservez les journaux, le commit du workflow et la référence permettant un retour arrière.
05 Essai macOS et critères de fusion
L’essai doit répondre à une question précise : le workflow corrigé réalise-t-il encore le travail prévu dans votre environnement cible ? Ne vous limitez pas à un démarrage réussi. Une action peut être résolue puis échouer plus tard, ou produire un résultat que l’étape suivante ne consomme pas comme prévu.
Procédez dans cet ordre :
- Choisissez une tâche minimale représentative. Gardez l’action Homebrew concernée et les étapes indispensables à son exécution. Évitez de mêler au premier essai une publication ou une opération irréversible.
- Exécutez la branche isolée sur le macOS cible. Notez le système, le type de runner tel qu’il est configuré dans le workflow, le commit du workflow et la référence d’action testée. Ne mélangez pas les résultats de plusieurs environnements.
- Confirmez la résolution et le démarrage. Le journal doit montrer que GitHub Actions a trouvé la référence choisie et que l’action a commencé à s’exécuter. Une étape verte placée avant l’action ne prouve pas que la migration est correcte.
- Contrôlez les entrées et les sorties. Comparez les paramètres transmis avec ceux attendus par la version retenue. Vérifiez que les sorties effectivement produites sont disponibles pour les étapes suivantes et qu’aucun nom ou format supposé n’a changé.
- Validez le résultat fonctionnel. Examinez le résultat de la tâche Homebrew elle-même, puis vérifiez que le comportement attendu par le projet est reproductible. Comparez les journaux avec ceux de la version précédemment validée ; signalez tout écart au lieu de le classer automatiquement comme sans conséquence.
- Vérifiez le périmètre de sécurité. Confirmez que les permissions, secrets et conditions d’exécution restent conformes au dépôt. Consultez la documentation de syntaxe et les contrôles de sécurité GitHub cités plus haut si le workflow utilise des permissions explicites ou des politiques de dépendances.
- Consignez la décision et le retour arrière. Enregistrez la référence adoptée, la preuve de validation, le commit et la personne chargée de la revue. Si le test échoue, restaurez la dernière référence confirmée comme fonctionnelle, à condition qu’elle soit encore disponible et autorisée ; ne réintroduisez pas une référence
@mastersupprimée.
Une validation est exploitable si une autre personne peut relier le résultat à la référence et au commit testés. Un simple message « le workflow passe » ne permet pas de savoir quel environnement a été exécuté ni quelle dépendance était en place. Gardez au minimum le journal pertinent, le diff de uses: et le résultat de la tâche Homebrew.
À retenir : tant que l’action ne s’est pas résolue et que la tâche réelle n’a pas été vérifiée dans le macOS cible, le changement n’est pas prêt à être généralisé. Un test de syntaxe seul ne valide ni les sorties ni le résultat du travail.
Si vos mainteneurs ne disposent pas d’un Mac de test pour cet essai, commencez par définir l’environnement nécessaire et l’isolation attendue. Une machine distante peut permettre de réaliser une vérification macOS, mais elle ne dispense ni de contrôler les permissions ni de conserver des preuves reproductibles. Vous pouvez examiner les options de location de Mac de CALMVPS pour déterminer si un environnement temporaire convient à votre plan de validation.
06 Déploiement progressif et réexamen
Après un essai réussi, fusionnez la correction selon la revue habituelle, puis surveillez le premier passage du workflow concerné. Pour plusieurs dépôts, procédez par groupes que votre équipe peut suivre : cela limite le périmètre de diagnostic si une différence entre projets apparaît. Ne recopiez pas aveuglément la même ligne lorsque les actions, entrées ou politiques de sécurité diffèrent.
Définissez aussi les événements qui déclencheront une nouvelle vérification : publication d’une nouvelle version Homebrew/actions, modification des consignes officielles, changement de politique GitHub Actions ou mise à jour du workflow qui consomme une sortie de l’action. La politique de mise à jour doit nommer un responsable et préciser où retrouver les preuves du dernier essai. Vérifiez les sources officielles avant toute nouvelle migration, en particulier l’annonce Homebrew 7.0.0 et les publications de Homebrew/actions.
Si votre solution actuelle repose uniquement sur une machine Linux, elle ne peut pas exécuter à elle seule les étapes qui exigent macOS ; si elle dépend d’un Mac de développeur partagé, l’accès et la répétabilité des essais peuvent être contraints. À l’inverse, louer un Mac n’est pas automatiquement pertinent pour une charge continue et prévisible, ni pour un test nécessitant un périphérique physique local : dans ces cas, comparez le coût d’usage à long terme et les besoins matériels avant de choisir. Pour une vérification isolée ou une période de migration, CALMVPS peut être une option à évaluer plutôt que d’acheter immédiatement une machine dédiée. Consultez les formules de location CALMVPS, puis lancez d’abord un essai correspondant à votre workflow avant d’y confier une validation continue.