Homebrew 7 GitHub Actionsのエラーはどう移行する?2026年ガイド

Homebrew/actions/*@masterは継続利用せず、CalVerリリースまたは完全なSHAに置き換えてください。対象はHomebrew 7後のワークフローを修正する場合で、@mainへの変更だけを長期的な固定策にしないことが重要です。まず隔離したmacOS CIで入力、出力、実際のビルド結果を確認します。

HomebrewのFormula、Cask、関連プロジェクトを保守し、古いブランチ参照を直したい方に向けた手順です。
macOS CIの担当者や、Actionのバージョンを審査・固定する開発基盤の責任者にも役立ちます。

更新日:2026年11月16日。Homebrew 7.0.0の告知、移行記録、Actionの公開状況を確認して記載しています。公開前に参照先の現行情報も再確認してください。

01 最初に把握する:失敗の原因と対象範囲

Homebrew 7.0.0の告知では、Homebrew/actions/*@masterが削除され、CalVerリリースまたは完全なSHAへの移行が案内されています。@mainも移行対象として挙げられています。告知内容と変更履歴は、Homebrew 7.0.0の発表およびHomebrew/actionsの移行記録で確認できます。

古い@master参照が解決できない場合、単なる一時的な通信障害と決めつけて再実行を繰り返さないでください。GitHub Actionsのワークフローでは、usesの参照がActionを指定します。ブランチ名を変更しても、古い参照が自動的に新しい参照へ置き換わるわけではありません。ワークフロー構文の公式説明を確認し、失敗した参照そのものを特定します。

まず、リポジトリ内のワークフロー、再利用ワークフロー、スクリプトを検索します。例えば次のように検索し、該当箇所だけでなく呼び出し元と後続処理も記録してください。

grep -RInE 'Homebrew/actions/.*@(master|main)' .github scripts

この検索結果は出発点です。別のディレクトリや生成されたワークフローを使うプロジェクトでは、検索対象をリポジトリの構成に合わせて広げます。各参照について、用途、受け取る入力、後続ステップが読む出力、実行に必要な権限を移行メモに残します。

02 参照先を棚卸しし、修正対象を確定する

@masterと@mainを同じ扱いにしないでください。@masterはHomebrew 7.0.0の告知で削除が確認されている参照です。一方、@mainは公式に移行が勧められている参照ですが、切り替えただけで固定策を実現したことにはなりません。

Homebrew/actions公式リポジトリで、対象Actionの現在のリリースと利用方法を確認します。参照の記録は、例えば次のように作るとレビューしやすくなります。

  • ワークフローファイルとジョブ名
  • 呼び出しているAction名と現在の参照
  • 入力値、利用している出力、後続ステップ
  • 必要な権限と実行条件
  • 移行後の候補バージョンと確認担当者

Actionの呼び出しが再利用ワークフローや独自スクリプトの内側にある場合、単純な文字列置換では見つからないことがあります。呼び出し元から実行結果の利用箇所までたどり、一覧の漏れを防ぎます。

03 CalVerと完全なSHAはどう選ぶか

Homebrew/actionsのCalVerリリースと完全なSHAは、どちらも候補になります。CalVerはリリースの追跡と更新作業をチームの運用に組み込みやすく、完全なSHAは特定のコミットに参照を固定してレビューできます。利用可能なリリースタグや推奨方法は変わる可能性があるため、公式リポジトリの公開情報で対象Actionの状態を確認してから決めてください。

判断は、更新を誰が、どのような審査を経て反映するかで分けます。

  • 定期的にリリースを確認し、更新をレビューして反映できるなら、CalVerリリースを選びます。
  • コミット単位で変更を審査し、更新を明示的に管理するなら、完全なSHAを選びます。
  • チームに更新担当者やレビュー手順がないなら、まず担当者と更新ルールを決めます。参照だけ変更して運用を未定のままにしないでください。

@mainは公式に移行が勧められている対象ですが、長期的なバージョン固定を担う参照として扱うべきではありません。移行先を選ぶ際は、ブランチ参照からリリースタグまたは完全なSHAへ移す方針を立て、差分をレビュー可能な形で記録します。GitHubは依存関係の固定や安全なAction利用に関する考え方をワークフロー依存関係のロックファイル資料と安全な利用のガイドで説明しています。

チームの更新手順から移行先を決める

  • 更新を定期レビューしてリリースを追えるなら、CalVerを候補にします。
  • 変更をコミット単位で審査し、参照を明示的に更新するなら、完全なSHAを候補にします。
  • どちらの運用もできていないなら、先に更新担当者と承認手順を決めます。
  • 参照先が最新か判断できない場合は、推測で記入せず、公式リポジトリで公開状況を確認してから変更します。

04 隔離ブランチで置き換え、設定差を点検する

変更は一括置換ではなく、棚卸しした参照ごとに行います。次の例では、組織名、リポジトリ名、Action名、参照先をすべてプレースホルダーにしています。実在するAction名やSHAとして使わないでください。

steps:
  - name: Run Homebrew action
    uses: <ORG>/<REPO>/<ACTION>@<CALVER_OR_FULL_SHA>
    with:
      <INPUT_NAME>: <VALUE>

<CALVER_OR_FULL_SHA>には、確認済みのCalVerリリースまたは完全なSHAを設定します。移行前後で入力名や既定値が変わっていないか、Actionが出力する値を後続ステップが正しく参照しているかも調べます。

権限は必要以上に広げず、ステップの順序や実行条件も比較してください。ワークフロー構文とActionの入力・出力の扱いは、GitHub Actionsの構文資料に沿って確認します。リポジトリで許可するActionの参照形式を制限している場合は、設定が移行後の参照と整合するかもGitHub Actionsのリポジトリ設定資料で確認してください。

05 macOS CIで試走し、実行結果を受け入れる

ローカルでYAMLの差分が正しく見えても、macOS CIでActionが解決され、期待する作業が完了するとは限りません。対象の実行環境に近い隔離ワークフローで試走し、ログと結果を保存します。実環境の検証先が必要な場合は、先にリモートMac開発環境の選択肢を確認し、用途に合うか判断してください。

検証は、対象のHomebrew処理に絞った最小ワークフローから始めます。成功表示だけで判定せず、Actionの参照解決、入力の受け渡し、後続ステップでの出力利用、ビルドまたは検査結果の再現性を個別に確かめてください。

試走チェックリスト

  • [ ] 参照先が公式情報で確認したCalVerまたは完全なSHAになっている
  • [ ] Actionを取得し、対象のステップが実行される
  • [ ] 入力値が想定した形で渡される
  • [ ] 後続ステップが必要な出力を読み取れる
  • [ ] 必要な権限だけで処理が完了する
  • [ ] Homebrewタスクの結果とログを保存できる
  • [ ] Runner、macOSのシステム情報、ワークフローのコミットを記録している

記録がないまま失敗すると、Action変更、Runner環境、ワークフロー差分のどれが原因か切り分けにくくなります。比較できるログとコミット情報をそろえてから、移行前後の結果を評価します。

06 段階公開と回帰時の戻し方を決める

試走で問題がなければ、対象を限定して公開します。失敗した場合は、事前に確認した利用可能なバージョンへ戻す手順を用意し、変更責任者と判断基準をレビュー時に明記してください。確認していない古い@masterへ戻すことを、回避策として前提にしてはいけません。

判断する状況 選ぶ対応 公開前に残す証拠
リリース更新をレビューして継続的に反映できる 確認済みのCalVerを候補にする 公式のリリース情報、差分、試走ログ
コミット単位で参照を固定し、更新を審査できる 確認済みの完全なSHAを候補にする SHAの出所、レビュー記録、試走ログ
参照先やActionの状態を確認できていない 変更を保留して公式情報を再確認する 未確認事項と確認担当者
macOS CIで入力・出力・処理結果のいずれかが未確認 公開せず、隔離環境で再試行する 失敗ログ、環境情報、修正差分
段階 実施内容 次へ進む条件
棚卸し ワークフローと呼び出し元を調べ、参照を一覧化する @masterと@mainの対象箇所を説明できる
選定 チームの更新・審査方法に合わせて参照を決める 参照先を公式情報で確認している
試走 隔離したmacOS CIで対象タスクを実行する 入力、出力、実処理をログで確認できる
公開 対象を限定して変更を反映する 回帰時の戻し先と担当者が決まっている
再確認 公開情報や上流の移行案内に変更がないか確認する 変更を検知した際の確認経路がある

複数リポジトリへ広げる際は、同じ変更をまとめて適用するのではなく、各リポジトリの入力・出力・権限と実行結果を確認してから進めます。公式の告知、Actionのリリース、対象ワークフローのいずれかに変更があれば、移行メモを見直してください。

07 実機に近い検証環境が必要な場合

手元の環境だけで確認する場合、macOS CIと同じ条件を用意しにくいことがあります。既存のLinux環境ではmacOS固有の処理を確認できず、手元のMacは共有テストや継続稼働に向かない場合があります。Macの購入は専用環境を確保しやすい一方、今回の検証だけが目的なら導入・保守の負担も比較が必要です。

まずは現在のワークフローで隔離試走を行い、必要な環境、利用期間、運用担当者を明確にしてください。継続的な検証に使うMac環境を外部に任せる選択肢を検討するなら、CALMVPSの料金情報で条件を確認し、自前のMac運用と比較したうえで、CALMVPSの利用案内を参照してください。環境条件が合わない場合や、物理機器への直接接続が必要な場合は、リモート環境を選ばず手元の実機で検証するのが適切です。