「タグ指定」のGitHub Actionsは固定されていない:一人開発の全リポジトリをSHA固定する手順と、壊れた箇所の計測方法
2025年3月、人気のGitHub Actions「tj-actions/changed-files」で、既存のバージョンタグが悪意あるコミットを指すよう書き換えられた事例が報告された(CVE-2025-30066)。CI/CD(ソフトウェアの自動ビルド・テスト・公開の仕組み)のログ経由で、認証情報が露出し得る内容だった。利用側が @v45 のようなタグで指定していた場合、ワークフローのファイルを1行も変えていなくても、実行される中身だけが入れ替わり得る。
GitHub公式ドキュメントは、サードパーティ製アクションを使う際、フルレングスのコミットSHA(変更履歴の1点を指す40文字の識別子)で指定する方法を、アクションを不変のリリースとして使う唯一の方法として案内している。
本記事は、一人の開発者が管理する複数リポジトリを対象に、全アクションをSHA固定する場合の棚卸し手順、所要時間の計測方法、壊れた箇所の記録と整理の方針をまとめたものである。
本記事の数値について 時間・件数・PR数は環境によって大きく変わる。そのため、ここでは具体的な「実測値」を掲げず、計測用のテンプレートと集計方法を示す。表の「記入欄」は、読者自身のリポジトリで埋める前提である。創作した数字で議論するより、自分の環境の数字で判断するほうが意味がある、という整理による。
そもそもタグ指定とSHA固定では何が違うのか
タグは「後から指す先を変えられる」
actions/checkout@v4 のようなタグやブランチ指定は、アクションの作者(または作者のアカウントを奪った第三者)の操作で、指す先を後から変えられる。スプレッドシートで言えば、更新のたびに中身が変わる外部ブック参照に近い。ファイル名(タグ名)は同じでも、開くたびに数値(コード)が変わり得る。
SHAは内容と一意に対応する
コミットSHAはコミットの内容から計算される識別子で、同じSHAのまま中身だけ差し替えることはできない。タグ名をSHAに置き換えることは、外部参照を「値のコピー」に変える作業に似ている。
書き方は次のとおり。可読性のため、元のバージョンをコメントで残すのが一般的である。
# 変更前
- uses: actions/checkout@v4
# 変更後(SHAは例示用のプレースホルダー)
- uses: actions/checkout@<40文字のコミットSHA> # v4.2.2
SHA固定でも防げないリスクがある
- 入れ子の依存:固定したアクションが内部で呼ぶ別のアクションは、その作者がタグ指定していれば可変のままである。
- Dockerイメージ:Dockerコンテナ型のアクションは、イメージのタグやその中の依存が別の確認対象になる。
- フォーク経由の同名コミット:GitHubでは、フォークのコミットが元リポジトリ経由でも参照できる仕組みがある。そのため、貼り付けたSHAが公式リポジトリ由来かどうかを確認する必要がある。
個人開発のリポジトリでは、まず何を棚卸しすべきか
抽出対象は uses: 行
監査の対象は、全リポジトリの .github/workflows にある uses: 行である。GitHubのコード検索でも拾えるが、一括で表にするならローカルにクローンしてスクリプトで抽出するほうが再現性が高い。
# 1) 自分のリポジトリ(フォーク・アーカイブ除く)を浅くクローン
gh repo list OWNER --limit 200 --no-archived --source \
--json nameWithOwner -q '.[].nameWithOwner' \
| while read r; do gh repo clone "$r" "work/${r#*/}" -- --depth 1 -q; done
# 2) uses: 行を CSV に(列: repo,file,line,action,ref)
grep -rnoE 'uses:[[:space:]]*[^[:space:]#]+' work/*/.github/workflows \
| sed -E 's#^work/([^/]+)/\.github/workflows/([^:]+):([0-9]+):uses:[[:space:]]*#\1,\2,\3,#' \
| sed -E 's/@/,/' > uses.csv
注意点が2つある。./ で始まるローカルアクションには @ がないため、列が1つ少ない行になる。また docker://image@sha256:... は @ の後ろがダイジェストとして ref 列に入る。どちらも後で目視確認する前提で、除外せず残しておく。
集計項目
CSVをExcelやGoogleスプレッドシートに読み込み、次の項目を集計する。
| 集計項目 | 求め方の例 | 記入欄 |
|---|---|---|
| リポジトリ数 | repo列の固有数(ピボットテーブル) | |
| ワークフロー数 | repo+file の固有数 | |
uses: 行の総数 |
行数 | |
| 固有のアクション数 | action列の固有数(UNIQUE 関数など) |
|
公式(actions/*)の行数 |
=COUNTIF(D:D,"actions/*") |
|
| 第三者の行数 | 総数 − 公式 − ローカル | |
| 固定済み / 未固定 | ref列の文字数が40か(下記) |
固定済みの判定は、次の式で近似できる。
=IF(LEN(E2)=40,"固定済み","未固定")
厳密には「40文字の16進数」かどうかを見る必要があるが、棚卸しの段階ではこの近似で足りる。docker:// のダイジェスト(sha256: で始まる)は別に数える。
偏りを見る
ピボットテーブルで「アクション名 × 使用リポジトリ数」を並べると、少数のアクションが大半の行を占める、いわゆるロングテール型の分布になっていることが多いと見られる。この場合、上位数個を固定するだけで、固定済みの割合が大きく動く。
メンテナンスが止まっているアクションを見つける
固有のアクション一覧ができたら、次の観点で確認する。
- 最終コミット日、最新リリース日
- アーカイブされていないか
- 未対応のまま残っているIssueや、非推奨の告知
更新が止まったアクションは、固定しても脆弱性修正が入らない。削除、公式アクションへの置き換え、数行のシェルスクリプトでの自前実装のいずれかが候補になる。固定作業の前に件数を減らしておくと、後の作業量も減る。
全件をSHA固定するのにどれくらい時間がかかるのか
3方式を同じ条件で比べる
| 方式 | 内容 | 向いている状況 |
|---|---|---|
| 手作業 | タグからSHAを調べて書き換える | 件数が少ない |
| ピン留め支援ツール | pinact や Renovate の helpers:pinGitHubActionDigests プリセットなど |
件数が多い、定期的に再実行したい |
| 自前スクリプト | gh api でSHAを引いて置換 |
独自ルールがある |
手作業でのSHA取得には、次のコマンドが使える。
gh api repos/actions/checkout/commits/v4.2.2 -q .sha
この commits エンドポイントはタグ名を受け取り、最終的なコミットのSHAを返す。Webの画面でタグを開いてコピーする方法より、取り違えが起きにくい。
計測方針
比較を公平にするため、次のルールで記録する。
- 計測の単位は「
uses:1行あたりの秒数」と「リポジトリ単位の合計」の2種類とする。 - 計測の開始は、対象リポジトリを開いた時点とする。終了は、CIが全て成功した時点(差分の確認とPR作成を含む)とする。
- 調査や設定ファイルの準備にかかった時間は、「初回のみ」の欄に分けて書く。
記録テンプレート
| リポジトリ | uses: 行数 |
方式 | 作業時間(分) | 1行あたり(分) | 再実行(CI修正)回数 |
|---|---|---|---|---|---|
| (記入) | |||||
| (記入) | |||||
| 合計 |
見るべきポイント
- 件数に比例するか:行数を横軸、作業時間を縦軸にした散布図を描く。直線に乗らない点があれば、その点が「手間のかかったリポジトリ」である。
- 特定のリポジトリに集中するか:合計時間の多くを少数のリポジトリが占める場合、その原因(後述の入れ子の依存やDocker指定など)を調べる価値がある。
- ツール導入の損益分岐:ツールの導入・設定時間を、手作業との差分(1行あたりの時間差)で割ると、何行以上でツールが有利かの目安になる。
固定したあと、実際に何が壊れたのか
原因別に分類して記録する
固定後にCIが失敗した場合は、原因を次の5分類で記録する。
| 分類 | 典型的な状況 | 確認方法 |
|---|---|---|
| ① SHAの取り違え | コピー時の欠落、別リポジトリのSHA、フォーク由来のSHA | 公式リポジトリの該当コミットが存在するか確認 |
| ② タグが指す先の誤認 | 注釈付きタグ(annotated tag)のタグオブジェクトのSHAを、コミットのSHAと取り違える | git ls-remote <URL> 'refs/tags/<tag>^{}' でコミットを確認 |
| ③ 入れ子の依存 | 複合アクション内の未固定参照、古い依存 | 固定したSHA時点の action.yml を読む |
| ④ Docker指定 | docker:// のタグ指定、ダイジェストの扱い |
image: の記述を確認 |
| ⑤ 権限設定 | permissions 不足、組織ポリシーによる拒否 |
ログのエラーメッセージ |
①と②は「作業ミス」、③と④は「構造上の問題」、⑤は「設定の問題」と位置づけられる。固定の目的がタグの書き換え対策である以上、③と④は失敗が出なくても確認が必要な領域である。
複合アクション内の未固定依存
複合アクション(composite action、複数の手順を1つにまとめたアクション)は、内部の action.yml に別のアクションへの uses: を持てる。こちらにトップレベルの固定は及ばない。
# 利用側:SHAで固定している
- uses: some-owner/some-composite@<SHA> # v1.2.3
# some-composite の action.yml 内:
# - uses: other-owner/other-action@v2 ← タグ指定のまま
利用側は、固定したSHA時点の action.yml を読み、内部の uses: がタグ指定でないかを確認する。タグ指定だった場合の選択肢は、作者にSHA固定を依頼する、別のアクションに替える、自前で書く、のいずれかになる。
再利用可能ワークフローと docker:// の違い
| 指定の種類 | 固定の方法 | 補足 |
|---|---|---|
| 通常のアクション | owner/repo@<SHA> |
基本形 |
| 再利用可能ワークフロー | owner/repo/.github/workflows/x.yml@<SHA> |
SHAでの指定が可能。呼び出し先の中身の依存は別途確認 |
docker:// 形式 |
docker://image@sha256:<ダイジェスト> |
Gitのコミットではなく、イメージのダイジェストで固定する |
ローカルアクション(./) |
不要 | 同じリポジトリ内のため、リポジトリの履歴で管理される |
Dockerのダイジェストは、コンテナイメージ版の「SHA」に当たる。ただしコミットSHAと違い、公式リポジトリとの照合手段がイメージの提供元(レジストリ)に依存する点には注意が必要である。
失敗から修復までの記録
壊れた箇所は、次のテンプレートで記録する。
| # | リポジトリ | 分類(①〜⑤) | 失敗の症状 | 修正内容 | 検知から修復までの時間(分) |
|---|---|---|---|---|---|
| 1 | (記入) | ||||
| 2 | (記入) |
分類ごとに修復時間の平均を出すと、「どの種類の問題が重いか」が分かる。
固定したアクションの更新は、どう維持すればよいのか
固定は「自動追従」を手放すこと
タグ指定なら、@v4 の指す先が更新されれば自動的に新しい版が使われる。SHA固定ではそれが起きない。放置すれば、アクション側で脆弱性が修正されても取り込めない。固定は、更新の自動化とセットで機能すると言える。
Dependabotで更新PRを受け取る
DependabotはGitHub Actionsのエコシステムに対応しており、SHAで固定したアクションについても更新PRを作成できる。バージョンのコメント(# v4.2.2)があれば、それも合わせて更新される。設定例は次のとおり。
# .github/dependabot.yml
version: 2
updates:
- package-ecosystem: "github-actions"
directory: "/"
schedule:
interval: "weekly"
groups:
actions:
patterns:
- "*"
groups を使うと、複数のアクション更新を1つのPRにまとめられる。PRの本数が確認負担に直結するため、複数リポジトリを持つ場合は特に効果が大きいと見られる。
PRの量を計測する
| 期間 | リポジトリ数 | 作成されたPR数 | 1週間あたり | groups 使用の有無 |
|---|---|---|---|---|
| 1〜4週目(記入) |
groups あり・なしで比較すると、確認負担を左右する要因を切り分けられる。
更新PRの確認は最小限にする
すべてのPRで全コードを読むのは現実的でない。次の順に絞る運用案が考えられる。
- 差分とリリースノートの確認:変更の種類(バグ修正か、破壊的変更か)を把握する。
- CIの成否確認:失敗していれば原因を調べ、成功していれば次へ進む。
- 第三者アクションのみ追加確認:公式(
actions/*)は軽く、第三者は差分をより丁寧に見る。
SHA固定を「必須」にする設定
GitHubには、リポジトリ・組織・Enterpriseの設定で、許可するアクションを制限するポリシーがある。2025年には、このポリシーでSHA固定を必須にする機能も案内された。未固定のアクションを使うワークフローを失敗させられるため、新しい未固定の参照が紛れ込むのを防げる。
ただし、提供範囲(プランや対象単位)や設定画面の場所は変わり得る。導入前に、最新の公式ドキュメントで確認が必要である。個人開発では、「自分自身のうっかり防止」や、複数の個人リポジトリを組織にまとめている場合の一括適用に使いどころがあると見られる。
個人開発でもここまでやる価値はあるのか
侵害時の影響は小さくない
個人リポジトリでも、CIが次のような権限を持つ場合は多い。
- パッケージ公開用のトークン(npm、PyPIなど)
- クラウドへのデプロイ権限
- リポジトリへの書き込み権限(
GITHUB_TOKEN)
CI上で漏えいしたトークンは、そのプロジェクトの利用者に届く成果物の改ざんにつながり得る。影響の大きさはリポジトリの規模ではなく、CIが扱う権限の大きさで決まると