github-actions-pipeline-builder

GitHub Actions パイプラインビルダー

高速で信頼性が高く、安全な、本番環境向け CI/CD パイプラインを GitHub Actions で構築するエキスパートです。

使用する場面

✅ 次の場合に使用：

• すべてのコミットで自動テストを実行する
• ステージング環境／本番環境にデプロイする
• Docker イメージをビルドして公開する
• バージョン管理を伴うリリースを自動化する
• セキュリティスキャンと依存関係の監査を行う
• コード品質をチェックする（リンティング、型チェック）
• 複数環境のワークフローを運用する

❌ 次の場合には使用しない：

• GitHub 以外のリポジトリ（Jenkins、CircleCI などを使用）
• 専用の CI/CD ツールのほうが適している複雑なパイプライン
• セルフホストランナー（高度なパターンで扱います）

クイック決定ツリー

Does your project need:
├── Testing on every PR? → GitHub Actions
├── Automated deployments? → GitHub Actions
├── Matrix builds (Node 16, 18, 20)? → GitHub Actions
├── Secrets management? → GitHub Actions secrets
├── Multi-cloud deployments? → GitHub Actions + OIDC
└── Sub-second builds? → Consider build caching

---

技術の選択

GitHub Actions と代替手段の比較

2024 年に GitHub Actions を選ぶ理由：

• ネイティブ統合：サードパーティのセットアップが不要です
• パブリックリポジトリでは無料：プライベートリポジトリでは月 2000 分
• マトリックスビルド：複数のバージョンを並列でテストできます
• マーケットプレイス：事前構築済みのアクションが 10,000 個以上あります
• OIDC サポート：鍵を使わないクラウドデプロイが可能です

年表：

• 2019 年：GitHub Actions がリリースされました
• 2020 年：OSS プロジェクトの標準になりました
• 2022 年：安全なクラウド認証のための OIDC サポートが追加されました
• 2024 年：GitHub リポジトリ向けの事実上の CI/CD になりました

代替手段を使用する場面

シナリオ	使用するもの	理由
セルフホストの GitLab	GitLab CI	ネイティブ統合
複雑なエンタープライズワークフロー	Jenkins	より柔軟
Bitbucket リポジトリ	Bitbucket Pipelines	ネイティブ統合
非常に大規模なリポジトリ（>10GB）	BuildKite	モノレポにより適している

---

よくあるアンチパターン

アンチパターン 1：依存関係のキャッシュがない

初心者の考え：「一貫性を保つため、毎回依存関係を新規インストールする」

問題：変更されていない依存関係のインストールに、ビルドごとに 2～5 分かかります。

誤った方法：

# ❌ Slow: Downloads all dependencies every run
- name: Install dependencies
  run: npm install

正しい方法：

# ✅ Fast: Cache dependencies, only download changes
- name: Cache node_modules
  uses: actions/cache@v3
  with:
    path: ~/.npm
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-node-

- name: Install dependencies
  run: npm ci  # Faster than npm install

効果：インストール時間を 3 分から 30 秒に短縮できます。

年表：

• 2020 年以前：キャッシュのないワークフローが大半でした
• 2020 年以降：キャッシュが標準になりました
• 2024 年：セットアップアクションにキャッシュ機能が組み込まれています

---

アンチパターン 2：YAML の重複（マトリックスビルドを使わない）

問題：異なる Node バージョン向けのワークフローをコピー＆ペーストしています。

誤った方法：

# ❌ Duplicated workflows
jobs:
  test-node-16:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 16
      - run: npm test

  test-node-18:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - run: npm test

  test-node-20:
    # ... same steps again

正しい方法：

# ✅ DRY: Matrix build
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [16, 18, 20]
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'npm'
      - run: npm ci
      - run: npm test

メリット：YAML を 66% 削減でき、テストを並列で実行できます。

---

アンチパターン 3：コード内のシークレット

問題：API キーやトークンをハードコードすると、リポジトリ上で見える状態になります。

兆候：セキュリティスキャナーの警告、認証情報の漏えい。

正しい方法：

# ✅ Use GitHub Secrets
- name: Deploy to production
  env:
    API_KEY: ${{ secrets.PRODUCTION_API_KEY }}
    AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY }}
  run: |
    ./deploy.sh

シークレットの設定：

1. リポジトリの Settings → Secrets and variables → Actions
2. New repository secret
3. 名前：PRODUCTION_API_KEY、値：sk-...

年表：

• 2022 年以前：一部のチームが .env ファイルをコミットしていました
• 2022 年以降：GitHub のシークレットスキャンにより、キーを含むコミットがブロックされます
• 2024 年：OIDC により、長期間有効な認証情報が不要になります

---

アンチパターン 4：失敗通知がない

問題：CI が失敗しても通知されず、チームが何時間も気づきません。

正しい方法：

# ✅ Slack notification on failure
- name: Notify on failure
  if: failure()
  uses: slackapi/slack-github-action@v1
  with:
    payload: |
      {
        "text": "❌ Build failed: ${{ github.event.head_commit.message }}",
        "blocks": [
          {
            "type": "section",
            "text": {
              "type": "mrkdwn",
              "text": "*Build Failed*\n<${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}|View logs>"
            }
          }
        ]
      }
  env:
    SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK }}

---

アンチパターン 5：すべてのコミットで全テストを実行する

問題：フィードバックループが遅くなります（テストスイートに 10 分以上かかります）。

兆候：開発者がこまめなコミットを避けるようになります。

正しい方法：

# ✅ Fast feedback: Run subset on PR, full suite on merge
on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  quick-tests:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - run: npm run test:unit  # Fast: 2 minutes

  full-tests:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - run: npm run test  # Slow: 10 minutes (unit + integration + e2e)

代替案：変更されたファイルのアクションを使い、影響を受けるテストだけを実行します。

---

実装パターン

パターン 1：基本的な CI パイプライン

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 18
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run linter
        run: npm run lint

      - name: Run type check
        run: npm run typecheck

      - name: Run tests
        run: npm test

      - name: Build
        run: npm run build

パターン 2：複数環境へのデプロイ

name: Deploy

on:
  push:
    branches:
      - main        # → staging
      - production  # → production

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: ${{ github.ref_name }}  # staging or production

    steps:
      - uses: actions/checkout@v3

      - name: Deploy to ${{ github.ref_name }}
        run: |
          if [ "${{ github.ref_name }}" == "production" ]; then
            ./deploy.sh production
          else
            ./deploy.sh staging
          fi
        env:
          API_KEY: ${{ secrets.API_KEY }}
          DATABASE_URL: ${{ secrets.DATABASE_URL }}

パターン 3：リリースの自動化

name: Release

on:
  push:
    tags:
      - 'v*'  # Trigger on version tags (v1.0.0)

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write  # Required for creating releases

    steps:
      - uses: actions/checkout@v3

      - name: Build artifacts
        run: npm run build

      - name: Create GitHub Release
        uses: softprops/action-gh-release@v1
        with:
          files: |
            dist/**
          body: |
            ## What's Changed
            See CHANGELOG.md for details.
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Publish to npm
        run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

パターン 4：Docker のビルドとプッシュ

name: Docker

on:
  push:
    branches: [main]

jobs:
  build-and-push:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v2

      - name: Login to DockerHub
        uses: docker/login-action@v2
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Build and push
        uses: docker/build-push-action@v4
        with:
          context: .
          push: true
          tags: |
            myapp:latest
            myapp:${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

---

本番環境向けチェックリスト

□ Dependency caching configured
□ Matrix builds for multiple versions
□ Secrets stored in GitHub Secrets (not code)
□ Failure notifications (Slack, email, etc.)
□ Deploy previews for pull requests
□ Staging → Production promotion workflow
□ Release automation with versioning
□ Docker layer caching enabled
□ CODEOWNERS file for required reviews
□ Branch protection rules enabled
□ Status checks required before merge
□ Security scanning (Dependabot, CodeQL)

---

使用する場面と避ける場面

シナリオ	GitHub Actions を使用するか
GitHub でホストされているリポジトリ	✅ はい
マトリックスビルドが必要	✅ はい
AWS／GCP／Azure にデプロイする	✅ はい（OIDC を使用）
GitLab リポジトリ	❌ いいえ。GitLab CI を使用
非常に大規模なモノレポ	⚠️ 場合によります。BuildKite を検討してください
GUI パイプラインビルダーが必要	❌ いいえ。Jenkins／Azure DevOps を使用

---

参考資料

• /references/advanced-caching.md - ビルドを高速化するキャッシュ戦略
• /references/oidc-deployments.md - キーレスのクラウド認証
• /references/security-hardening.md - セキュリティのベストプラクティス

スクリプト

• scripts/workflow_validator.ts - YAML の構文をローカルで検証します
• scripts/action_usage_analyzer.ts - 古いアクションを見つけます

アセット

• assets/workflows/ - すぐに使えるワークフローテンプレート

---

このスキルの対象: CI/CD パイプライン | GitHub Actions ワークフロー | マトリックスビルド | キャッシュ | デプロイ | リリースの自動化