github-actions

GitHub Actions の基礎知識

高度な知識：包括的なドキュメントを参照するには、テクノロジーに github-actions を指定して mcp__documentation__fetch_docs を使用してください。

基本的な CI ワークフロー

# .github/workflows/ci.yml
name: CI

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

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

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

      - name: Install dependencies
        run: npm ci

      - name: Run linter
        run: npm run lint

      - name: Run tests
        run: npm test

      - name: Build
        run: npm run build

データベースを使用する場合

jobs:
  test:
    runs-on: ubuntu-latest

    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_USER: test
          POSTGRES_PASSWORD: test
          POSTGRES_DB: testdb
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5

    env:
      DATABASE_URL: postgresql://test:test@localhost:5432/testdb

    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npx prisma migrate deploy
      - run: npm test

デプロイワークフロー

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Deploy to Vercel
        uses: amondnet/vercel-action@v25
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
          vercel-args: '--prod'

マトリックス戦略

jobs:
  test:
    strategy:
      matrix:
        node: [18, 20, 22]
        os: [ubuntu-latest, macos-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}

再利用可能なワークフロー

# .github/workflows/test.yml
on:
  workflow_call:

jobs:
  test:
    runs-on: ubuntu-latest
    steps: [...]

# Usage in another workflow
jobs:
  call-tests:
    uses: ./.github/workflows/test.yml

このスキルを使用しない場合

次の場合は、このスキルを使用しないでください：

• GitLab CI/CD（.gitlab-ci.yml）を使用する場合 — 構文が異なります
• Jenkins、CircleCI、Travis CI を使用する場合 — プラットフォームが異なります
• ローカルの開発環境をセットアップする場合 — docker-compose スキルを使用してください
• Docker イメージのみをビルドする場合（CI は不要） — docker スキルを使用してください
• Bitbucket Pipelines を使用する場合 — プラットフォームが異なります

アンチパターン

アンチパターン	問題	解決策
権限を制限していない	セキュリティリスク、過剰なアクセス	ジョブごとに最小限の permissions: を設定する
@v1 のようなアクションタグを使用する	更新時に破壊的変更が起きる	SHA に固定する：@60edb5dd545a775178f52524783378180af0d1f8
ログにシークレットを出力する	認証情報が漏洩する	シークレットを echo しないでください。env: のみを使用してください
タイムアウトを設定していない	ジョブが際限なく実行され、時間を消費する	ジョブに timeout-minutes: 15 を設定する
キャッシュを使用していない	ビルドが遅くなり、時間を浪費する	actions/cache で依存関係をキャッシュする
すべてのコミットで実行する	CI の実行時間を浪費する	paths: フィルターを使うか、pull_request: のみを使用する
バージョンをハードコードする	環境に一貫性がなくなる	マトリックス戦略または環境変数を使用する
アーティファクトの保持期間に上限がない	ストレージコストが高くなる	アーティファクトに retention-days: 7 を設定する
シークレットをコードに保存する	セキュリティ侵害につながる	GitHub Secrets を使用し、コミットしない
ブランチ保護がない	CI チェックを回避できてしまう	ブランチルールでステータスチェックを必須にする

トラブルシューティングのクイックガイド

問題	原因の特定	対処方法
ワークフローがトリガーされない	イベントまたはブランチフィルターが正しくない	on: トリガーとブランチ名を確認する
ジョブが何も表示せず失敗する	スクリプトエラーが無視されている	`
キャッシュが一度もヒットしない	キャッシュキーが変化している	安定したキーを使用する：hashFiles('**/package-lock.json')
「Resource not accessible」	権限が正しくない	ジョブに必要な permissions: を追加する
PR でシークレットを使用できない	フォークからはアクセスできない	pull_request_target を（慎重に）使用するか、シークレットを使うステップをスキップする
アーティファクトのアップロードに失敗する	パスが存在しない	ビルドの出力パスを確認し、if: always() を使用する
マトリックスジョブが失敗する	1 つの構成の失敗がすべてに影響する	fail-fast: false を使い、ほかのジョブを続行する
ワークフローに時間がかかりすぎる	キャッシュがなく、ジョブが逐次実行されている	キャッシュを追加し、needs: で並列化する
「Context access might be invalid」	コンテキストの構文が正しくない	${{ }} 構文を使用し、コンテキストが利用可能か確認する
別のワークフローをトリガーできない	トークンに権限がない	書き込み権限を持つ PAT または GITHUB_TOKEN を使用する

本番環境への対応

セキュリティのベストプラクティス

# Secure workflow
name: CI

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

permissions:
  contents: read
  pull-requests: write

jobs:
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 15

    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false

      # Pin actions to SHA for security
      - uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
        with:
          node-version: '20'

      # Use environment secrets
      - name: Deploy
        env:
          API_KEY: ${{ secrets.API_KEY }}
        run: |
          # Never echo secrets
          ./deploy.sh

キャッシュ戦略

jobs:
  build:
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      # Custom caching
      - name: Cache dependencies
        uses: actions/cache@v4
        with:
          path: |
            ~/.npm
            node_modules
          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-node-

      # Turbo cache for monorepos
      - name: Cache Turbo
        uses: actions/cache@v4
        with:
          path: .turbo
          key: ${{ runner.os }}-turbo-${{ github.sha }}
          restore-keys: |
            ${{ runner.os }}-turbo-

アーティファクト管理

jobs:
  build:
    steps:
      - name: Build
        run: npm run build

      - name: Upload build artifacts
        uses: actions/upload-artifact@v4
        with:
          name: build-${{ github.sha }}
          path: dist/
          retention-days: 7

  deploy:
    needs: build
    steps:
      - name: Download artifacts
        uses: actions/download-artifact@v4
        with:
          name: build-${{ github.sha }}
          path: dist/

環境の保護

jobs:
  deploy-staging:
    runs-on: ubuntu-latest
    environment: staging

  deploy-production:
    runs-on: ubuntu-latest
    needs: deploy-staging
    environment:
      name: production
      url: https://example.com
    concurrency:
      group: production-deploy
      cancel-in-progress: false

エラー処理

jobs:
  build:
    steps:
      - name: Run tests
        id: tests
        continue-on-error: true
        run: npm test

      - name: Upload test results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: test-results
          path: coverage/

      - name: Check test status
        if: steps.tests.outcome == 'failure'
        run: |
          echo "Tests failed"
          exit 1

      - name: Notify on failure
        if: failure()
        uses: slackapi/slack-github-action@v1
        with:
          payload: |
            {"text": "Build failed: ${{ github.repository }}"}
        env:
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK }}

Dependabot の設定

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    groups:
      development-dependencies:
        patterns:
          - "@types/*"
          - "eslint*"
          - "prettier*"

  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"

リリースワークフロー

name: Release

on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write

    steps:
      - uses: actions/checkout@v4

      - name: Build
        run: npm run build

      - name: Create Release
        uses: softprops/action-gh-release@v2
        with:
          files: dist/*
          generate_release_notes: true

モニタリング指標

指標	目標
ビルド成功率	> 95%
ビルド時間	< 10min
キャッシュヒット率	> 80%
デプロイ頻度	必要に応じて

チェックリスト

• 最小限の権限を宣言している
• アクションを SHA に固定している
• ログにシークレットを出していない
• キャッシュを設定している
• タイムアウトを設定している
• エラー通知を設定している
• 環境保護ルールを設定している
• Dependabot を有効にしている
• ブランチ保護ルールを設定している
• 同時実行制御を設定している

リファレンスドキュメント

• キャッシュ
• シークレット