Contents
1. GitHub Actions の全体像と主要コンポーネント
GitHub Actions は workflow → job → step → runner という階層で構成されます。各レイヤーの役割と相互関係を把握すれば、複雑なパイプラインでもスムーズに設計できます。
1.1 workflow(ワークフロー)
workflow はリポジトリ内の *.yml ファイルで定義し、いつ パイプラインが走るか(トリガー)と 何を 実行するか(jobs)を記述します。
1.2 job(ジョブ)
job は単一の実行単位です。OS イメージや環境変数、依存関係 (needs:) を設定でき、デフォルトでは 並列 に走ります。
1.3 step(ステップ)
step はシェルコマンドか外部 Action の呼び出しで構成されます。uses: で公式・サードパーティの Action を組み込み、run: で自由なスクリプトを書きます。
1.4 runner(ランナー)
runner はジョブを実行するマシンです。GitHub が提供する hosted runners(Ubuntu, Windows, macOS)と、企業が管理する self‑hosted runners の二種類があります。ランナーは OS・ハードウェアリソースを選択でき、プライベートネットワークへのアクセスが必要なデプロイに最適です。
2. ワークフローファイルの配置と基本構文
GitHub が自動で検出する場所は .github/workflows/ ディレクトリです。このディレクトリ配下に置いた YAML がすべて workflow として認識されます。
2.1 ディレクトリ作成とファイル雛形
以下のコマンドで必要なフォルダを作成し、最小構成の ci.yml を配置します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
mkdir -p .github/workflows cat > .github/workflows/ci.yml <<'EOS' name: CI on: push: branches: [ main ] pull_request: branches: [ main ] jobs: build-test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Hello run: echo "GitHub Actions が起動しました" EOS |
2.2 基本構文のポイント
| キー | 説明 |
|---|---|
name: |
ワークフロー一覧に表示される名前(任意) |
on: |
イベントトリガー。ブランチやタグ、スケジュールなど多彩な指定が可能 |
jobs: |
実行するジョブ集合。1 つ以上必須 |
この雛形にビルド・テスト・デプロイのロジックを追加していくことで、フルスタック CI/CD が完成します。
3. ビルド・テストステージのベストプラクティス
言語やツールチェーンごとに最適化したジョブを作成し、マトリックスビルド と キャッシュ を組み合わせることで、実行時間と網羅性の両立が可能です。
3.1 最新 Action バージョンの利用(2026年時点)
actions/checkout@v4actions/setup-node@v3actions/cache@v4actions/setup-java@v4docker/setup-buildx-action@v3docker/login-action@v2docker/build-push-action@v6
※ 各 Action は公式ドキュメントで最新版を随時確認してください。
3.2 Node.js ビルド&テスト(マトリックス+キャッシュ)
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 |
jobs: node-ci: runs-on: ubuntu-latest strategy: matrix: node-version: [16, 18, 20] # 複数バージョンを同時走査 steps: - uses: actions/checkout@v4 - name: Cache npm dependencies uses: actions/cache@v4 with: path: ~/.npm key: ${{ runner.os }}-node-${{ matrix.node-version }}-${{ hashFiles('package-lock.json') }} restore-keys: | ${{ runner.os }}-node-${{ matrix.node-version }}- - name: Setup Node.js ${{ matrix.node-version }} uses: actions/setup-node@v3 with: node-version: ${{ matrix.node-version }} - run: npm ci - run: npm test - name: Upload coverage reports uses: actions/upload-artifact@v3 with: name: coverage-${{ matrix.node-version }} path: coverage/ |
3.3 Java (Maven) ビルド&テスト
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 |
java-ci: runs-on: ubuntu-latest strategy: matrix: jdk-version: [11, 17] steps: - uses: actions/checkout@v4 - name: Cache Maven repository uses: actions/cache@v4 with: path: ~/.m2/repository key: ${{ runner.os }}-maven-${{ matrix.jdk-version }}-${{ hashFiles('**/pom.xml') }} restore-keys: | ${{ runner.os }}-maven-${{ matrix.jdk-version }}- - name: Setup JDK ${{ matrix.jdk-version }} uses: actions/setup-java@v4 with: distribution: temurin java-version: ${{ matrix.jdk-version }} - run: mvn -B clean verify - name: Upload Surefire reports uses: actions/upload-artifact@v3 with: name: surefire-${{ matrix.jdk-version }} path: target/surefire-reports/ |
3.4 Docker イメージのビルド&プッシュ
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
docker-ci: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Set up Buildx (キャッシュ有効化) uses: docker/setup-buildx-action@v3 - name: Login to GitHub Container Registry uses: docker/login-action@v2 with: registry: ghcr.io username: ${{ github.actor }} password: ${{ secrets.GITHUB_TOKEN }} - name: Build and push Docker image uses: docker/build-push-action@v6 with: context: . tags: ghcr.io/${{ github.repository }}:${{ github.sha }} cache-from: type=registry,ref=ghcr.io/${{ github.repository }}:cache cache-to: type=registry,ref=ghcr.io/${{ github.repository }}:cache,mode=max push: true |
3.5 キャッシュ戦略のまとめ
| 言語 | キャッシュ対象ディレクトリ | 推奨キー例 |
|---|---|---|
| Node.js | ~/.npm |
${{ runner.os }}-node-${{ matrix.node-version }}-${{ hashFiles('package-lock.json') }} |
| Java (Maven) | ~/.m2/repository |
${{ runner.os }}-maven-${{ matrix.jdk-version }}-${{ hashFiles('**/pom.xml') }} |
| Docker | BuildKit レイヤーキャッシュ | type=registry,ref=ghcr.io/${{ github.repository }}:cache |
キャッシュキーに hashFiles を組み込むと、依存ファイルが変更されたときだけ新しいキャッシュが生成され、無駄な再取得を防げます。
4. デプロイ戦略と環境保護設定
CI が成功したら次は実稼働環境へのデプロイです。主要クラウド(AWS, GCP, Azure)それぞれのサンプルと、GitHub の Environment Protection 機能による安全策を紹介します。
4.1 環境保護の概念
| 項目 | 説明 |
|---|---|
| Environment | production, staging など名前で管理し、URLやシークレットと紐付けられる |
| Required reviewers | デプロイ前に指定ユーザー/チームの承認が必須になる |
| Wait timer | 承認待機時間を設定し、緊急デプロイの抑止に利用できる |
設定手順:
Settings → Environmentsで環境を作成 → 「Protection rules」からレビュー・タイマー・シークレットを追加。
4.2 AWS Elastic Beanstalk デプロイ例
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
deploy-aws: needs: [node-ci, java-ci, docker-ci] runs-on: ubuntu-latest environment: name: production # 環境保護が自動適用される steps: - uses: actions/checkout@v4 - name: Configure AWS credentials uses: aws-actions/configure-aws-credentials@v3 with: aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }} aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }} aws-region: us-east-1 - name: Deploy to Elastic Beanstalk run: | zip -r app.zip . eb init my-app --region us-east-1 eb deploy prod-env |
4.3 Google Cloud Run デプロイ例
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
deploy-gcp: needs: [node-ci, java-ci, docker-ci] runs-on: ubuntu-latest environment: name: staging steps: - uses: actions/checkout@v4 - name: Authenticate to GCP uses: google-github-actions/auth@v2 with: credentials_json: ${{ secrets.GCP_SA_KEY }} - name: Set up Cloud SDK uses: google-github-actions/setup-gcloud@v2 - name: Deploy to Cloud Run run: | gcloud builds submit --tag gcr.io/${{ env.PROJECT_ID }}/my-service:${{ github.sha }} gcloud run deploy my-service \ --image gcr.io/${{ env.PROJECT_ID }}/my-service:${{ github.sha }} \ --region us-central1 \ --platform managed \ --allow-unauthenticated |
4.4 Azure App Service デプロイ例
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
deploy-azure: needs: [node-ci, java-ci, docker-ci] runs-on: ubuntu-latest environment: name: production steps: - uses: actions/checkout@v4 - name: Login to Azure uses: azure/login@v2 with: creds: ${{ secrets.AZURE_CREDENTIALS }} - name: Deploy to App Service uses: azure/webapps-deploy@v3 with: app-name: my-app-service slot-name: production publish-profile: ${{ secrets.AZURE_PUBLISH_PROFILE }} package: . |
4.5 デプロイフローの全体像
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
name: CI/CD パイプライン on: push: branches: [ main ] pull_request: jobs: # ビルド・テストは前節参照(node-ci, java-ci, docker-ci) # --------------------------------------------------------- deploy-aws: ... # 上記例 deploy-gcp: ... # 上記例 deploy-azure: ... # 上記例 |
5. 再利用可能ワークフローとテンプレート化
大規模組織では同一のビルド・デプロイロジックが多数のリポジトリに散在します。workflow_call と テンプレートリポジトリ を活用すれば、変更は 1 カ所だけで全体に反映できます。
5.1 再利用可能ワークフロー(共通 CI)
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 |
# .github/workflows/common-ci.yml name: Common CI on: workflow_call: inputs: node-version: required: true type: string java-version: required: false type: string secrets: GITHUB_TOKEN: required: true jobs: node-test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Setup Node ${{ inputs.node-version }} uses: actions/setup-node@v3 with: node-version: ${{ inputs.node-version }} - run: npm ci - run: npm test java-test: if: ${{ inputs.java-version != '' }} runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Setup JDK ${{ inputs.java-version }} uses: actions/setup-java@v4 with: distribution: temurin java-version: ${{ inputs.java-version }} - run: mvn -B verify |
5.2 呼び出し側ワークフロー(プロジェクト固有)
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
# .github/workflows/ci.yml name: Project CI on: push: branches: [ main ] pull_request: jobs: run-common-ci: uses: ./.github/workflows/common-ci.yml with: node-version: '20' java-version: '' # Java が不要な場合は空文字 secrets: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} |
5.3 組織テンプレートリポジトリ
- 作成:
org/common-workflowsリポジトリにtemplate-deploy.ymlを配置 - 内容(環境名だけを受け取るシンプルなデプロイ)
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
# org/common-workflows/.github/workflows/template-deploy.yml name: Deploy Template on: workflow_call: inputs: environment: required: true type: string jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Dummy deploy step run: echo "Deploying to ${{ inputs.environment }} ..." |
- 各プロジェクトからの呼び出し
|
1 2 3 4 5 6 7 8 |
jobs: prod-deploy: uses: org/common-workflows/.github/workflows/template-deploy.yml@v1 with: environment: production secrets: PRODUCTION_TOKEN: ${{ secrets.PRODUCTION_TOKEN }} |
5.4 効果のまとめ
| メリット | 詳細 |
|---|---|
| 一元管理 | workflow を更新すれば全リポジトリに即反映 |
| パラメータ化 | inputs により言語バージョンや環境名を柔軟に切り替え可能 |
| 可視性向上 | 呼び出し側は「何が呼ばれるか」だけで済むためコード量が減少 |
6. 監視・通知・トラブルシューティング
CI/CD の信頼性を保つには、実行結果の可視化と迅速なアラートが不可欠です。GitHub が提供する標準機能に加え、外部ツールとの連携方法も示します。
6.1 GitHub Actions のログ閲覧
- Actions タブ → 該当 workflow → ジョブ → ステップをクリックでリアルタイムの標準出力・エラーが確認できる
github.event.workflow_runコンテキストを活用すれば、実行時間や成功率を外部モニタリングサービスへ送信可能
|
1 2 3 4 5 6 7 |
- name: Send metrics to external endpoint if: always() run: | curl -X POST https://monitor.example.com/metrics \ -H "Content-Type: application/json" \ -d '{"workflow":"${{ github.workflow }}","run_id":${{ github.run_id }},"conclusion":"${{ job.status }}"}' |
6.2 Slack / Microsoft Teams への自動通知
|
1 2 3 4 5 6 7 8 9 10 11 12 |
- name: Notify Slack on failure if: failure() uses: slackapi/slack-github-action@v1.24.0 with: channel-id: ${{ secrets.SLACK_CHANNEL_ID }} payload: | { "text": ":x: *${{ github.workflow }}* が失敗しました。ブランチ `${{ github.ref_name }}`" } env: SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }} |
Teams 向けは microsoft/teams-notify-action@v2 などを同様に設定します。
6.3 よくあるエラーと対策
| エラー | 主な原因 | 推奨解決策 |
|---|---|---|
| 403 Forbidden(権限不足) | シークレットや PAT のスコープが足りない | repo, write:packages など必要なスコープを付与し、シークレットを更新 |
| Runner timeout | デフォルトは 6 時間。長時間ジョブは途中で停止 | timeout-minutes: を明示的に延長するか、ステップ単位で分割 |
| キャッシュヒット率低下 | キーが固定化されすぎる | hashFiles に対象ファイルを正しく指定し、依存変更時だけ新しいキーになるように設計 |
| Docker pull access denied | レジストリ認証情報が欠如または権限不足 | docker/login-action で正しいトークン/ユーザー名・パスワードを設定 |
6.4 次のアクションプラン
- 実装:本ガイドのサンプルをリポジトリに配置し、
git pushで動作確認 - カスタマイズ:プロジェクト固有の言語・デプロイ先に合わせてジョブやシークレットを調整
- モニタリング導入:メトリクス送信と Slack 通知を有効化し、失敗時のアラート体制を確立
- 定期レビュー:キャッシュヒット率・ビルド時間を月次で分析し、マトリックスや依存バージョンの最適化を継続
まとめ
- 全体像 → workflow → job → step → runner の階層構造を把握
- 必須ファイル →
.github/workflows/に配置する YAML が自動検知される - ビルド・テストはマトリックスとキャッシュで高速化、最新 Action バージョンを常に使用
- デプロイは主要クラウドへ直接実行し、Environment Protection で安全性確保
- 再利用可能ワークフローでコード重複を排除し、組織全体のメンテナンスコスト削減
- 監視・通知は GitHub の UI と外部チャットツールを併用し、障害時に即対応
これらを順番に導入すれば、信頼性が高く、スケーラブルな CI/CD パイプラインを短期間で構築できます。ぜひ本稿の手順を実際のリポジトリで試し、継続的改善サイクルへとつなげてください。