github-actions

GitHub Actions

概要

GitHub Actions は、GitHub リポジトリから直接、ビルド、テスト、デプロイのパイプラインを自動化する CI/CD プラットフォームです。ワークフローは .github/workflows/ 内の YAML ファイルで、プッシュ、プルリクエスト、スケジュール、手動実行などのイベントをトリガーとして実行されます。各ワークフローには、GitHub ホステッドまたはセルフホストのランナーで実行される 1 つ以上のジョブが含まれます。

使用する場面： 自動テスト、継続的デプロイ、リリースの自動化、スケジュールされたタスク、マルチプラットフォームビルド、依存関係の更新、コンテナの公開、コード品質チェック、セキュリティスキャン。

使用しない場面： 長時間稼働するサービス（適切なホスティングプラットフォームを使用）、ランナーの制限を超える高負荷な計算タスク（ジョブのタイムアウトは 6 時間）、実行間で永続的な状態を必要とするタスク（外部ストレージを使用）、リアルタイムのイベント処理（サーバーを使った Webhook を使用）。

クイックリファレンス

パターン	構文／アクション	主なポイント
プッシュトリガー	on: push: branches: [main]	ブランチ、パス、タグでフィルター
PR トリガー	on: pull_request: types: [opened, synchronize]	デフォルトは opened、synchronize、reopened
スケジュールトリガー	on: schedule: - cron: '0 6 * * 1'	UTC のみ、最小間隔は 5 分
手動トリガー	on: workflow_dispatch: inputs:	手動実行用に型付き入力を定義
ジョブの依存関係	needs: [build, test]	ジョブを順次または並列で実行
条件付きジョブ	if: github.ref == 'refs/heads/main'	式ベースでジョブ／ステップをフィルター
マトリックス戦略	strategy: matrix: node: [18, 20, 22]	組み合わせごとにジョブを生成
依存関係キャッシュ	actions/cache@v5	ハッシュベースのキーと restore-keys によるフォールバック
キャッシュ付きセットアップ	actions/setup-node@v6 with cache: 'pnpm'	パッケージマネージャー向けの組み込みキャッシュ
アーティファクトのアップロード	actions/upload-artifact@v4	ジョブ間でデータを共有する、または出力を保持する
アーティファクトのダウンロード	actions/download-artifact@v4	以前のジョブからアーティファクトを取得
再利用可能なワークフロー	uses: ./.github/workflows/reusable.yml	workflow_call トリガーで呼び出す
コンポジットアクション	action.yml with using: composite	複数のステップを 1 つのアクションにまとめる
同時実行	concurrency: group: ${{ github.ref }}	重複した実行をキャンセルまたはキューに追加
環境シークレット	${{ secrets.API_KEY }}	リポジトリ、組織、または環境にスコープを設定
OIDC 認証	permissions: id-token: write	クラウドプロバイダー向けの短命トークン
ステップの出力	echo "key=value" >> "$GITHUB_OUTPUT"	ステップ間およびジョブ間でデータを渡す
サービスコンテナ	services: postgres: image: postgres:16	統合テスト用のサイドカーコンテナ
タイムアウト	timeout-minutes: 30	ハングしたジョブやステップを速やかに失敗させる
アテステーション	actions/attest-build-provenance@v3	サプライチェーン向けの SLSA ビルド来歴

式とコンテキスト

コンテキスト	例	説明
github	github.ref_name, github.sha	イベントのメタデータ、リポジトリ情報、実行者
env	env.NODE_ENV	現在のスコープの環境変数
secrets	secrets.API_KEY	暗号化されたシークレット（ログではマスクされます）
inputs	inputs.environment	ワークフローのディスパッチまたは再利用可能な入力
matrix	matrix.node	現在のマトリックスの組み合わせ値
steps	steps.build.outputs.version	前のステップからの出力
needs	needs.prepare.outputs.tag	依存するジョブからの出力
runner	runner.os, runner.arch	ランナー環境の情報
vars	vars.DEPLOY_URL	リポジトリまたは組織の構成変数

よくある間違い

間違い	正しいパターン
古いメジャーバージョンのアクションを使用する	現行のメジャーバージョン（@v6）またはコミット SHA に固定する
persist-credentials: false の指定漏れ	カスタムトークンまたは OIDC を使用する場合は、チェックアウト時に設定する
ワークフローレベルで広範な permissions を設定する	ワークフローレベルで permissions: {} を設定し、ジョブごとに権限を付与する
依存関係ファイルのハッシュを含まないキャッシュキー	キャッシュキーに hashFiles('**/pnpm-lock.yaml') を含める
if: 条件内でシークレットを使う	シークレットは if: 式で直接使用できません
pull_request_target を不用意に使う	pull_request_target から書き込み権限で PR のコードを実行しない
古い実行をキャンセルしない	cancel-in-progress: true を指定した concurrency を使用する
構造化データを単一のシークレットとして保存する	ログを適切にマスキングするため、値ごとに個別のシークレットを作成する
SHA で固定せずにアクションのタグを参照する	サプライチェーンの安全性を確保するため、サードパーティ製アクションを完全なコミット SHA に固定する
スクリプト内でランナーの OS をハードコードする	クロスプラットフォーム互換性のために runner.os コンテキストを使用する
restore-keys を指定せずに actions/cache を使用する	部分的に一致するキャッシュを取得できるよう、常に restore-keys を指定する
run: ブロック内でユーザー入力を展開する	スクリプトインジェクションを防ぐため、信頼できない値は env: 経由で渡す
ジョブに timeout-minutes を設定しない	ハングしたプロセスを速やかに失敗させるため、明示的なタイムアウトを設定する
スコープを限定せずに always() を使う	ステータスチェックと組み合わせる：if: always() && steps.x.outcome == 'success'

委任

• ワークフローのデバッグ：Explore エージェントを使用してワークフロー実行ログを調査します
• セキュリティ監査：Task エージェントを使用して権限とシークレットの使用状況を確認します
• コードレビュー：ワークフローの PR レビューを code-reviewer エージェントに委任します

参考資料

• ワークフローの構文、トリガー、ジョブ、ステップ、並行実行
• キャッシュ戦略とアーティファクト管理
• マトリックス戦略、再利用可能なワークフロー、複合アクション
• セキュリティ、シークレット、OIDC、権限の強化