github-actions

GitHub Actions

ワークフローは、認証情報を扱う本番コードとして捉えてください。セキュリティは信頼境界を、パフォーマンスはクリティカルパスを、正確性は実行グラフを基準にしてください。意図的に動作を維持し、変更した経路を検証してください。

プロセス

最初に、該当するすべてのモードを選択してください。

• 監査： 単独で選択された場合は、編集せずに調査して報告します。
• 変更： 既存のワークフローまたはDependabotの設定を診断して変更します。
• 作成： 新しいワークフロー、再利用可能なワークフロー、またはDependabotの設定を追加します。

複数のモードを組み合わせることもできます。監査と修正の依頼では、まず監査し、許可された指摘事項を修正して、修正済みと未対応の指摘事項を両方報告してください。

モードを選択した後、Dependabotのみを対象とするタスクでは、専門的なプロセスとしてDependabotと依存関係の自動化を使用してください。以下のワークフロー実行グラフのプロセスは、Dependabotによってトリガーされる、または依存関係の送信向けに生成されるリポジトリのワークフローにのみ適用してください。

1. 影響を受けるパイプラインを把握する

既存のワークフローでは、到達可能なすべてのローカルアクションと再利用可能なワークフローをたどってください。変更不可能な識別情報ごとにソースの読み取りを重複させず、呼び出し元のref、入力、シークレット、権限の上限、条件、環境、ランナーを考慮して、すべての呼び出しエッジを分析してください。再利用可能な契約が変更される可能性がある場合は、影響を受ける呼び出し元をすべて特定してください。新規作成の場合は、要求された動作から推測されるリポジトリの規約と候補コンポーネントを把握してください。

影響を受ける実行ブランチごとに、次を特定してください。

• イベント、アクター、ref、フォークとDependabotの動作、承認および保留のゲート、デフォルトブランチのセマンティクス、適用されるActionsポリシー
• 各ジョブが使用するコード、式、アーティファクト、キャッシュ、入力、ネットワークデータ
• 各ジョブが受け取るトークンの権限、シークレット、OIDCクレーム、環境、ランナーのアクセス権
• needs、条件、出力、マトリックス、バックグラウンドのライフサイクル、並行処理、キャンセルを含むジョブとステップのグラフ
• パッケージマネージャー、ロックファイル、スクリプト、ランタイムのバージョン、ランナーのラベル、既存のCI規約
• 必須チェック、デプロイの順序、リリース保証、ユーザーが依存する動作
• パフォーマンスまたはコストに関する作業では、目標とベースラインのゲートを満たしてください。コストに関しては、さらに証拠を収集して帰属させてください

確認したコンテキストが該当する場合は、対応する参照資料をすぐに読み込んでください。

観察された状況	参照先
攻撃者が権限を持つジョブに影響を及ぼせる	信頼境界マップとトークンの権限
特権イベントまたはデフォルトブランチのイベントがコントリビューターの影響を扱う	特権イベント
外部依存関係、チェックアウト、ローカルの./または$/アクション、あるいはワークフローポリシーが関係する	依存関係とワークフローガバナンス
シークレット、OIDC、環境、またはクラウド認証情報が関係する	シークレット、OIDC、環境
アーティファクトやキャッシュがジョブ、ワークフロー、参照、または信頼レベルをまたぐ、あるいはActionsの保持設定が変わる	アーティファクトの昇格またはキャッシュポイズニングの連鎖
セルフホストランナーまたはActionsポリシーが関係する	ランナーとネットワーク到達範囲またはプラットフォームの実行保護
ジョブの開始前に実行が保留される、承認待ちになる、またはブロックされる	承認ゲートと保留中の実行、およびポリシーによる拒否についてはプラットフォームの実行保護
run:ブロックが作成、変更、またはレビューされる	シェルのセマンティクス、式の境界、失敗の処理、およびワークフローデータ
run:ブロックが一時ファイルを書き込む	ランナーが管理する一時ストレージ
GitHub API、gh、またはgithub-scriptを使用する	まず最も限定的なAPIを選ぶ、次に対応するインターフェイスのセクション
workflow_dispatchをAPI経由で送信する、またはその実行を追跡する必要がある	ワークフローのディスパッチ
シークレットスキャンのカスタムパターンを自動化する	シークレットスキャンのカスタムパターン
Dependabotの設定、アラート、依存関係グラフ、依存関係の送信、プライベートレジストリ、またはDependabotのプルリクエストの動作が関係する	Dependabotと依存関係の自動化
出力、環境への書き込み、またはサマリーを使用する	ワークフローチャネル
イベント、フィルター、式、失敗、キャンセル、またはタイムアウトが関係する	イベントと参照、式、または失敗
同時実行、マトリックス、または再利用可能な契約が関係する	同時実行、マトリックス、または再利用可能なワークフロー
レイテンシー、コスト、並列処理、セットアップ、ランナー、キャッシュ、またはアーティファクトが関係する	対象とベースラインを明確にする、次に対応するパフォーマンスのセクション
Actionsのメトリクス、請求レポート、ダッシュボード、またはGitHubが生成したワークフローが関係する	エビデンスを収集して帰属を明らかにする
完了条件： 要求されたすべてのモードが選択されていること。影響を受けるすべてのワークフロー、呼び出し元、到達可能なローカル依存関係、および個別の呼び出しコンテキストが考慮されていること。すべての進入元、実行エッジ、機能、および動作上の契約がマッピングされていること。すべての Dependabot タスクが依存関係サーフェスのゲートを満たしていること。また、パフォーマンス作業が、リンク先の目標とベースラインのゲートを満たしていること。

2. 安全な実行グラフを構成する

選択したすべてのモードについて、マッピングしたグラフを以下の目標と比較します。監査のみのモードでは、証拠に基づく差異を記録し、編集は行いません。変更または作成では、この目標に沿って構成します。監査と組み合わせる場合は、変更の証拠として差異を残します。

• 必要なコンテキストを提供するイベントのうち、最小限の権限で済むものを選びます。
• デフォルトで拒否するトークンのベースラインを設定し、各ジョブには必要な権限だけを付与します。
• 信頼されていない値が特権操作に渡る場合、それらの値によって実行、権限の選択、宛先、または副作用の範囲が制御されないよう制約します。
• データ、分離、またはライフサイクルのエッジのみを追加し、依存関係が満たされた独立した作業はすぐに開始します。
• 必須チェック、失敗、再試行、タイムアウト、キャンセル、および並行実行のセマンティクスを明確にします。
• デプロイとリリースには、保護された環境、不変の入力、および意図的なキューイングを設定します。
• スクリプトが依存する箇所では、ロック済みの依存関係インストールと明示的なシェルのセマンティクスを使用します。
• 以下の検証手順を用いて、すべての外部依存関係を不変にします。
• パフォーマンス変更は、リンク先の目標とベースラインに沿って構成し、起動、計算、キャッシュ、およびアーティファクト転送の作業を考慮します。

完了条件： 選択したすべての監査で、マッピングしたすべてのエッジを、読み込まれたすべてのルールと照合していること。選択したすべての変更または作成において、機能、信頼境界の通過、順序付け、必須の結果、およびデプロイのセマンティクスが正当化された目標グラフがあること。また、パフォーマンス設計には、実証に向けて証拠に基づく期待される影響が用意されていること。

3. 選択したすべてのモードを実行する

監査

影響度の高い順に指摘事項を記録します。監査のみのモードでは、編集せずに指摘事項を報告します。監査を変更と組み合わせる場合は、最終報告書で各指摘事項に修正済みまたは未対応の印を付けます。各指摘事項には、以下を含めます。

• 重大度と正確な file:line
• トリガーとなるイベント、アクター、または入力
• 具体的な失敗、権限、またはパフォーマンスの経路
• 最小限で安全な修正
• 検証の証拠、または具体的に不足している証拠

セキュリティに関する指摘には、信頼されていない要素の影響から機能に至る具体的な経路が必要です、多層防御とスタイル上の強化は分けて分類します。パフォーマンスに関する指摘には、測定されたボトルネック、またはクリティカルパスのモデルであることを明示したものが必要です。指摘事項が残っていない場合は、その旨を明記します。

変更

観測された動作を起点にします。問題ごとに、そのトリガー、入力、実行経路、および結果をたどります。問題の発生源で、まとまりのある最小限の変更によって修正します。問題の原因でない限り、パッケージマネージャー、ロックファイル、ランナー、命名、およびワークフローの慣例を維持します。再利用可能なワークフローの契約を変更する場合は、影響を受けるすべての呼び出し元を更新します。

作成

要求された動作を満たす、最小限の実行グラフを構築します。別の慣例を導入するのではなく、既存のローカルアクション、再利用可能なワークフロー、パッケージコマンド、および命名を再利用します。草案の作成後、生成したグラフを再度マッピングし、新たに該当するすべての参照を読み込みます。

外部参照が変更された場合

新しいアクション、再利用可能なワークフロー、コンテナイメージ、または明示的なアップグレードは、依存関係の変更として扱います。

1. 対象のリリースを特定し、そのリリースノートと移行ガイダンスを確認します。

2. アクションまたは再利用可能なワークフローのタグを、そのリポジトリ自身のコミットエンドポイントを通じて解決し、注釈付きタグからコミット SHA を取得します。

   repo='OWNER/REPOSITORY'
   tag='REVIEWED_RELEASE'
   gh api "repos/$repo/commits/$tag" --jq .sha
   gh api "repos/$repo/releases/tags/$tag" --jq '{tag_name,html_url,body}'
   

3. SHA がそのリポジトリに属していることを確認します。このワークフローに関係するソースの動作、アクションのメタデータ、ランタイムとランナーの最低要件、権限、入力の処理を調べます。GitHub.com では、JavaScript アクションは Node 24 でのみ実行され、Node 20 のオプトアウトは廃止されています。まだ runs.using: node20 を宣言しているリリースは Node 24 対応のものに置き換えます。また、macOS 13.4 以前または ARM32 のセルフホストランナーはサポート対象外として扱います。

4. コンテナイメージはダイジェストで固定します。ロックファイルに登録済みのワークフロー以外では、uses: にレビュー済みの SHA を設定します。uses: に SHA を指定する場合は、その SHA と人が読めるリリースコメントを併せて更新します。

5. リポジトリが .github/workflows/actions.lock を管理している場合は、対象のワークフローがその workflows セクションに記載されているか確認します。登録済みのワークフローでは、リポジトリ内の既存の形式で uses: を変更し、ロックファイルを手編集せずに gh actions-lock <workflow-path> でエントリを再生成します。パスを指定せずに実行すると、エントリが削除され、スキャン対象のすべてのワークフローが書き換えられます。新しいワークフローも同じ方法で登録します。通常の実行では既存のエントリが維持されるため、@main や @v4 のようなブランチまたは部分バージョンの固定は、--relock を指定した場合にのみ更新されます。ロックされたコミットが上流で参照できなくなっている場合、--relock はエラーを報告し、何も書き込みません。--accept-moved を追加する前に、上流の履歴を確認してください。ツールによる uses: の書き換えはそのまま維持します。浮動タグをロック対象の正確なリリースに置き換えたり、解決可能な ./ アクションを $/ に変換したりする場合があり、これによってコードの取得元が変わります（ローカルアクションの参照を参照）。登録前に、実行時に残る ./ アクション参照を修正します（$/ に移行する、パスを修正する、またはステップを削除する）か、他のワークフローパスのみを指定します。ドキュメントには、このようなワークフローはスキップされると記載されていますが、実行後に workflows セクションを確認してください。空のエントリは依存関係のないワークフローを登録することになり、その場合、GitHub はリモートアクションを拒否します。ワークフローがエントリとともに登録されるまでは、ステップ 4 が適用されます。登録済みワークフローに ./ アクション参照が残っている場合、これは処理を阻止するエラーになります。実行結果は何も書き込まれないため、再生成の前に $/ へ移行するか、パスを修正するか、ステップを削除してください。差分全体を確認し、変更された各 commit がレビュー済みの SHA であることを確かめます。変更された owner_id または repo_id は、承認する前に移管や置き換えの可能性を調査します。その後、gh actions-lock --verify を実行します。

明示的なアップグレードでは、指定した互換性のあるアップグレードが許可されます。無関係な作業中は、既存のバージョンが要求された動作を妨げる場合、または関連するセキュリティ上の欠陥がある場合を除き、既存のバージョンを維持します。

選択した各モードのゲートがすべて通過した時点で完了です。

• 監査： マッピングされた各エッジと読み込まれた各ルールを評価し、証拠に裏付けられた指摘事項、または指摘事項がないことを明示する結果を提示します。
• 変更： 要求された動作をすべて根本の箇所で修正し、影響を受ける呼び出し元を更新したうえで、結果のグラフを再マッピングします。
• 作成： 要求された動作をすべて、要件に適合する最小のグラフに含め、生成されたグラフを再マッピングします。
• 依存関係の変更： 変更された各参照とロックファイルのエントリがレビュー済みの不変オブジェクトを指し、そのランタイム契約が引き続き互換性を保っていることを確認します。
• Dependabot： 影響を受けるすべての依存関係の対象範囲と自動化プレーンが、Dependabot の基準を満たしていることを確認します。

4. ワークフローを検証する

1. リポジトリで設定されているワークフローの lint コマンドを実行します。設定されていない場合は、影響を受けるすべてのワークフローに対して actionlint を実行します。リンターは最新の構文に対応していない場合があります。actionlint 1.7.12 は、有効な $/ 参照、parallel、background、wait、wait-all、cancel、queue: max、cache-mode、vulnerability-alerts 権限、job.workflow_* コンテキスト、新しい ubuntu-26.04 などのランナーラベルをエラーとして扱います。各エラーが現在の GitHub Docs に照らして有効であることを確認し、有効な構文はそのまま維持して、リンターのバージョンと対応していない構文を報告します。それ以外の指摘はすべて修正します。
2. ローカルアクションを変更した場合は、設定されているスキーマツールでそのメタデータを検証します（GitHub.com では、JavaScript アクションは runs.using: node24 を宣言します）。さらに、宣言されている入力、出力、エントリーポイント、後処理動作、および代表的な呼び出し元を確認します。
3. 設定されている Actions セキュリティアナライザーをすべて実行し、その結果を信頼境界マップと照合します。静的解析はパスの追跡を補完するものです。
4. 変更した run: ステップの基盤となるコマンドを、リポジトリで固定されている依存関係の状態で安全に実行します。リリースまたはデプロイのコマンドには、文書化されたドライランを使用します。
5. パフォーマンスに関する変更では、パフォーマンス基準を満たします。リモート実行を利用できない場合は、正確な測定上のギャップを報告します。
6. Dependabot とワークフローの両方を変更した場合は、Dependabot の検証と基準も満たします。
7. 影響を受けるグラフ全体を再確認します。イベント、承認、保留、ポリシーのセマンティクス、権限、シークレット、OIDC、環境、ランナー、依存関係のピン留め、ローカルおよび再利用可能なコントラクト、出力、マトリックス、キャッシュ、アーティファクト、並行処理、バックグラウンド処理のバリア、および needs を確認します。
8. 実行したコマンドと結果を正確に報告します。利用できないランナー、認証情報、サービス、ポリシー、またはツールがあれば、検証上のギャップとして明記します。

完了条件： 影響を受けるすべてのワークフロー、変更したアクションマニフェスト、および変更した Dependabot 設定について、適用される検証に合格するか、ツールに関する正確な阻害要因が示されていること。変更した動作すべてに、直接実行した証拠または正確な外部要因による阻害があること。セキュリティに関する結論すべてで、追跡したパスが示されていること。また、すべての最適化がリンク先のパフォーマンス基準を満たしていること。