GitHub Actions CI/CD

概要

GitHub Actions は GitHub 公式の CI/CD プラットフォームで、ソフトウェアワークフローの自動化に対応しています。YAML ファイルでワークフローを定義して、リポジトリから直接コードのビルド、テスト、デプロイをイベント駆動型で自動化できます。

使い時

• すべてのプルリクエストでテストを自動化
• main ブランチへのマージ時にビルドとデプロイ
• 定期タスク(夜間ビルド、バックアップ)をスケジュール実行
• npm、PyPI、Docker Hub などのレジストリにパッケージを公開
• セキュリティスキャンとコード品質チェックを実行
• リリースプロセスとチェンジログ生成を自動化

クイックスタート

基本的なテストワークフロー

.github/workflows/test.yml を作成:

name: Test

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

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm test

---

GitHub Actions 完全ガイド

コア概念

ワークフロー

.github/workflows/ 内の YAML ファイルで、自動化パイプラインを定義します。

構造:

• Name: ワークフロー識別子
• Triggers: ワークフローを開始するイベント
• Jobs: 実行する 1 つ以上のジョブ
• Steps: 各ジョブ内のコマンド/アクション

name: CI Pipeline
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "Building project"

ジョブ

デフォルトでは並行実行される独立した実行ユニット。

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - run: npm run lint

  test:
    runs-on: ubuntu-latest
    needs: lint  # lint が完了するまで待機
    steps:
      - run: npm test

  deploy:
    runs-on: ubuntu-latest
    needs: [lint, test]  # 両方が完了するまで待機
    steps:
      - run: ./deploy.sh

ステップ

ジョブ内の順序付きコマンドまたはアクション。

steps:
  # 事前構築アクションを使用
  - uses: actions/checkout@v4

  # シェルコマンドを実行
  - run: npm install

  # 環境変数を持つ名前付きステップ
  - name: Run tests
    run: npm test
    env:
      NODE_ENV: test

アクション

再利用可能なコード単位(マーケットプレイスまたはカスタム)。

# 公式アクション
- uses: actions/checkout@v4

# サードパーティアクション
- uses: docker/build-push-action@v5
  with:
    context: .
    push: true
    tags: user/app:latest

# ローカルアクション
- uses: ./.github/actions/custom-action

ワークフロー構文

トリガー (on)

プッシュイベント

on:
  push:
    branches:
      - main
      - 'releases/**'  # ワイルドカードパターン
    tags:
      - 'v*'  # すべてのバージョンタグ
    paths:
      - 'src/**'
      - '!src/docs/**'  # docs を除外

プルリクエストイベント

on:
  pull_request:
    types: [opened, synchronize, reopened]
    branches: [main, develop]
    paths-ignore:
      - '**.md'
      - 'docs/**'

スケジュール (Cron)

on:
  schedule:
    # 毎日午前 2:30 UTC
    - cron: '30 2 * * *'
    # 月曜日午前 9:00 UTC
    - cron: '0 9 * * 1'

手動トリガー

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Deployment environment'
        required: true
        type: choice
        options:
          - staging
          - production
      version:
        description: 'Version to deploy'
        required: false
        default: 'latest'

複数のトリガー

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  schedule:
    - cron: '0 0 * * 0'  # 毎週
  workflow_dispatch:  # 手動

環境変数

ワークフローレベル

env:
  NODE_ENV: production
  API_URL: https://api.example.com

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - run: echo $NODE_ENV

ジョブレベル

jobs:
  test:
    runs-on: ubuntu-latest
    env:
      TEST_DATABASE: test_db
    steps:
      - run: pytest

ステップレベル

steps:
  - name: Build
    run: npm run build
    env:
      BUILD_TARGET: production

シークレット

リポジトリ設定に機密データを保存します。

steps:
  - name: Deploy
    run: ./deploy.sh
    env:
      API_KEY: ${{ secrets.API_KEY }}
      DATABASE_URL: ${{ secrets.DATABASE_URL }}

ベストプラクティス:

• コードにシークレットをコミットしない
• GitHub 暗号化シークレットを使用
• 特定の環境へのシークレットアクセスを制限
• 定期的にシークレットをローテーション

コンテキスト

github コンテキスト

リポジトリとワークフローの情報。

steps:
  - name: Print context
    run: |
      echo "Repository: ${{ github.repository }}"
      echo "Ref: ${{ github.ref }}"
      echo "SHA: ${{ github.sha }}"
      echo "Actor: ${{ github.actor }}"
      echo "Event: ${{ github.event_name }}"
      echo "Branch: ${{ github.ref_name }}"

env コンテキスト

環境変数にアクセス。

env:
  BUILD_ID: 12345

steps:
  - run: echo "Build ${{ env.BUILD_ID }}"

secrets コンテキスト

リポジトリシークレットにアクセス。

- run: echo "Token exists"
  env:
    TOKEN: ${{ secrets.GITHUB_TOKEN }}

matrix コンテキスト

マトリックス値にアクセス。

strategy:
  matrix:
    node: [18, 20, 22]
steps:
  - run: echo "Testing Node ${{ matrix.node }}"

needs コンテキスト

依存ジョブからの出力にアクセス。

jobs:
  build:
    outputs:
      version: ${{ steps.get_version.outputs.version }}
    steps:
      - id: get_version
        run: echo "version=1.2.3" >> $GITHUB_OUTPUT

  deploy:
    needs: build
    steps:
      - run: echo "Deploying ${{ needs.build.outputs.version }}"

ランナー

GitHub ホストランナー

jobs:
  ubuntu:
    runs-on: ubuntu-latest  # ubuntu-22.04

  macos:
    runs-on: macos-latest  # macOS 14

  windows:
    runs-on: windows-latest  # Windows 2022

  specific:
    runs-on: ubuntu-20.04  # 特定バージョン

利用可能なランナー:

• ubuntu-latest, ubuntu-22.04, ubuntu-20.04
• macos-latest, macos-14, macos-13
• windows-latest, windows-2022, windows-2019

セルフホストランナー

runs-on: self-hosted

# ラベル付き
runs-on: [self-hosted, linux, x64, gpu]

セットアップ:

1. Settings → Actions → Runners に移動
2. "New self-hosted runner" をクリック
3. プラットフォーム固有の指示に従う
4. ターゲット設定用にカスタムラベルを追加

マトリックス戦略

基本マトリックス

複数バージョン間でテスト。

strategy:
  matrix:
    node: [18, 20, 22]
    os: [ubuntu-latest, macos-latest, windows-latest]

runs-on: ${{ matrix.os }}
steps:
  - uses: actions/setup-node@v4
    with:
      node-version: ${{ matrix.node }}

Include/Exclude

strategy:
  matrix:
    node: [18, 20, 22]
    os: [ubuntu-latest, windows-latest]
    include:
      # 特定の組み合わせを追加
      - node: 22
        os: macos-latest
        experimental: true
    exclude:
      # 特定の組み合わせを削除
      - node: 18
        os: windows-latest

Fail-fast

strategy:
  fail-fast: false  # 1 つが失敗しても他を継続
  matrix:
    node: [18, 20, 22]

Max Parallel

strategy:
  max-parallel: 2  # 同時に 2 ジョブのみ実行
  matrix:
    node: [18, 20, 22]

一般的なアクション

コードをチェックアウト

- uses: actions/checkout@v4
  with:
    fetch-depth: 0  # チェンジログ用の完全履歴
    submodules: true  # サブモジュールを含める

Node.js をセットアップ

- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'npm'  # または 'yarn', 'pnpm'
    registry-url: 'https://registry.npmjs.org'

Python をセットアップ

- uses: actions/setup-python@v5
  with:
    python-version: '3.11'
    cache: 'pip'

Java をセットアップ

- uses: actions/setup-java@v4
  with:
    distribution: 'temurin'
    java-version: '17'
    cache: 'maven'

Go をセットアップ

- uses: actions/setup-go@v5
  with:
    go-version: '1.21'
    cache: true

依存関係をキャッシュ

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

アーティファクトをアップロード

- uses: actions/upload-artifact@v4
  with:
    name: build-output
    path: dist/
    retention-days: 7

アーティファクトをダウンロード

- uses: actions/download-artifact@v4
  with:
    name: build-output
    path: dist/

条件付き実行

if 条件

steps:
  - name: Deploy to production
    if: github.ref == 'refs/heads/main'
    run: ./deploy.sh

  - name: Deploy to staging
    if: github.ref == 'refs/heads/develop'
    run: ./deploy-staging.sh

  - name: Only on PR
    if: github.event_name == 'pull_request'
    run: echo "This is a PR"

  - name: On success
    if: success()
    run: echo "Previous steps succeeded"

  - name: On failure
    if: failure()
    run: echo "A step failed"

  - name: Always run
    if: always()
    run: echo "Cleanup tasks"

ジョブ条件

jobs:
  deploy:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - run: ./deploy.sh

フレームワーク固有のワークフロー

Node.js/TypeScript

name: Node.js CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [18, 20, 22]
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'npm'

      - run: npm ci

      - run: npm run lint

      - run: npm run type-check

      - run: npm test
        env:
          CI: true

      - run: npm run build

      - uses: codecov/codecov-action@v4
        if: matrix.node-version == 20
        with:
          token: ${{ secrets.CODECOV_TOKEN }}

Python

name: Python CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ['3.10', '3.11', '3.12']
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
          cache: 'pip'

      - run: pip install -r requirements.txt

      - run: pip install pytest pytest-cov mypy ruff

      - run: ruff check .

      - run: mypy .

      - run: pytest --cov=. --cov-report=xml

      - uses: codecov/codecov-action@v4
        if: matrix.python-version == '3.11'

Docker

name: Docker Build

on:
  push:
    branches: [main]
    tags: ['v*']

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

      - uses: docker/setup-buildx-action@v3

      - uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - uses: docker/metadata-action@v5
        id: meta
        with:
          images: user/app
          tags: |
            type=ref,event=branch
            type=semver,pattern={{version}}
            type=semver,pattern={{major}}.{{minor}}

      - uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

Next.js with Vercel

name: Next.js CI

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

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

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

      - run: npm ci

      - run: npm run lint

      - run: npm run build

      - run: npm test

  deploy-preview:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    needs: build
    steps:
      - uses: actions/checkout@v4

      - 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 }}

  deploy-production:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    needs: build
    steps:
      - uses: actions/checkout@v4

      - 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'

デプロイメントパターン

Vercel デプロイ

name: Deploy to Vercel

on:
  push:
    branches: [main]

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

      - 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'

Netlify デプロイ

name: Deploy to Netlify

on:
  push:
    branches: [main]

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

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

      - run: npm ci
      - run: npm run build

      - uses: netlify/actions/cli@master
        with:
          args: deploy --prod --dir=dist
        env:
          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}

AWS S3 + CloudFront

name: Deploy to AWS

on:
  push:
    branches: [main]

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

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

      - run: npm ci
      - run: npm run build

      - uses: aws-actions/configure-aws-credentials@v4
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: us-east-1

      - run: aws s3 sync dist/ s3://${{ secrets.S3_BUCKET }} --delete

      - run: |
          aws cloudfront create-invalidation \
            --distribution-id ${{ secrets.CLOUDFRONT_DISTRIBUTION_ID }} \
            --paths "/*"

Docker レジストリプッシュ

name: Publish Docker Image

on:
  release:
    types: [published]

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

      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: |
            ghcr.io/${{ github.repository }}:latest
            ghcr.io/${{ github.repository }}:${{ github.event.release.tag_name }}

テストワークフロー

カバレッジ付きユニットテスト

name: Test Coverage

on: [push, pull_request]

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

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

      - run: npm ci

      - run: npm test -- --coverage

      - uses: codecov/codecov-action@v4
        with:
          token: ${{ secrets.CODECOV_TOKEN }}
          files: ./coverage/coverage-final.json
          fail_ci_if_error: true

統合テスト

name: Integration Tests

on: [push, pull_request]

jobs:
  integration:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:15
        env:
          POSTGRES_PASSWORD: postgres
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
        ports:
          - 5432:5432

      redis:
        image: redis:7
        options: >-
          --health-cmd "redis-cli ping"
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
        ports:
          - 6379:6379

    steps:
      - uses: actions/checkout@v4

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

      - run: npm ci

      - run: npm run test:integration
        env:
          DATABASE_URL: postgresql://postgres:postgres@localhost:5432/test
          REDIS_URL: redis://localhost:6379

Playwright による E2E テスト

name: E2E Tests

on: [push, pull_request]

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

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

      - run: npm ci

      - run: npx playwright install --with-deps

      - run: npm run build

      - run: npm run test:e2e

      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: playwright-report
          path: playwright-report/
          retention-days: 30

リリース自動化

Semantic Release

name: Release

on:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # チェンジログ用の完全履歴

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

      - run: npm ci

      - run: npx semantic-release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

チェンジログ付きリリースを作成

name: Create Release

on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Generate changelog
        id: changelog
        run: |
          # コミットからチェンジログを生成
          CHANGELOG=$(git log $(git describe --tags --abbrev=0 HEAD^)..HEAD --pretty=format:"- %s (%h)" --no-merges)
          echo "changelog<<EOF" >> $GITHUB_OUTPUT
          echo "$CHANGELOG" >> $GITHUB_OUTPUT
          echo "EOF" >> $GITHUB_OUTPUT

      - uses: actions/create-release@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tag_name: ${{ github.ref_name }}
          release_name: Release ${{ github.ref_name }}
          body: |
            ## Changes
            ${{ steps.changelog.outputs.changelog }}
          draft: false
          prerelease: false

npm パッケージを公開

name: Publish to npm

on:
  release:
    types: [published]

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

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          registry-url: 'https://registry.npmjs.org'

      - run: npm ci

      - run: npm test

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

セキュリティスキャン

CodeQL 分析

name: CodeQL

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  schedule:
    - cron: '0 0 * * 1'  # 毎週

jobs:
  analyze:
    runs-on: ubuntu-latest
    permissions:
      actions: read
      contents: read
      security-events: write

    strategy:
      fail-fast: false
      matrix:
        language: ['javascript', 'python']

    steps:
      - uses: actions/checkout@v4

      - uses: github/codeql-action/init@v3
        with:
          languages: ${{ matrix.language }}

      - uses: github/codeql-action/autobuild@v3

      - uses: github/codeql-action/analyze@v3

依存関係スキャン

name: Dependency Check

on:
  push:
    branches: [main]
  schedule:
    - cron: '0 0 * * 1'

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

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

      - run: npm audit --audit-level=moderate

      - run: npx snyk test
        env:
          SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
        continue-on-error: true

Trivy コンテナスキャン

name: Container Security Scan

on:
  push:
    branches: [main]

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

      - run: docker build -t myapp:${{ github.sha }} .

      - uses: aquasecurity/trivy-action@master
        with:
          image-ref: 'myapp:${{ github.sha }}'
          format: 'sarif'
          output: 'trivy-results.sarif'

      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: 'trivy-results.sarif'

コンポジットアクション

.github/actions/ に再利用可能なアクションを作成します。

シンプルなコンポジットアクション

.github/actions/setup-project/action.yml:

name: 'Setup Project'
description: 'Install dependencies and cache'

inputs:
  node-version:
    description: 'Node.js version'
    required: false
    default: '20'

runs:
  using: 'composite'
  steps:
    - uses: actions/setup-node@v4
      with:
        node-version: ${{ inputs.node-version }}
        cache: 'npm'

    - run: npm ci
      shell: bash

使用方法:

steps:
  - uses: actions/checkout@v4
  - uses: ./.github/actions/setup-project
    with:
      node-version: '20'

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

.github/workflows/reusable-deploy.yml:

name: Reusable Deploy

on:
  workflow_call:
    inputs:
      environment:
        required: true
        type: string
    secrets:
      deploy-token:
        required: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: ${{ inputs.environment }}
    steps:
      - uses: actions/checkout@v4

      - run: ./deploy.sh
        env:
          DEPLOY_TOKEN: ${{ secrets.deploy-token }}
          ENVIRONMENT: ${{ inputs.environment }}

使用方法:

name: Deploy Production

on:
  push:
    branches: [main]

jobs:
  deploy:
    uses: ./.github/workflows/reusable-deploy.yml
    with:
      environment: production
    secrets:
      deploy-token: ${{ secrets.PRODUCTION_TOKEN }}

パフォーマンス最適化

依存関係キャッシング

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

Docker レイヤーキャッシング

- uses: docker/build-push-action@v5
  with:
    context: .
    cache-from: type=gha
    cache-to: type=gha,mode=max

並行実行

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - run: npm run lint

  test-unit:
    runs-on: ubuntu-latest
    steps:
      - run: npm run test:unit

  test-integration:
    runs-on: ubuntu-latest
    steps:
      - run: npm run test:integration

  # すべて並行実行

条件付きジョブ実行

jobs:
  deploy:
    # ドラフト PR ではデプロイをスキップ
    if: github.event.pull_request.draft == false
    runs-on: ubuntu-latest
    steps:
      - run: ./deploy.sh

ワークフローのデバッグ

デバッグログを有効化

リポジトリシークレットを設定:

• ACTIONS_RUNNER_DEBUG: true
• ACTIONS_STEP_DEBUG: true

デバッグステップ

- name: Debug Info
  run: |
    echo "Event: ${{ github.event_name }}"
    echo "Ref: ${{ github.ref }}"
    echo "SHA: ${{ github.sha }}"
    echo "Actor: ${{ github.actor }}"
    env

tmate による対話的デバッグ

- name: Setup tmate session
  if: failure()
  uses: mxschmitt/action-tmate@v3
  timeout-minutes: 15

ベストプラクティス

セキュリティ

• 機密データにはシークレットを使用
• アクションバージョンを SHA にピン留め: uses: actions/checkout@8e5e7e5a...
• トークン権限を最小化
• ブランチ保護環境で保護ルールを有効化
• 必須チェック付きブランチ保護を有効化

パフォーマンス

• 依存関係を積極的にキャッシュ
• マトリックス戦略を使用した並行テスト
• 可能な限りチェックアウト深度を最小化
• アーティファクトをジョブ間データ転送に使用
• 多段ビルドで Docker ビルドを最適化

保守性

• 一般的なパターンに再利用可能なワークフローを使用
• 反復ステップ用にコンポジットアクションを作成
• ワークフローの目的とトリガーをドキュメント化
• 意味のあるジョブ名とステップ名を使用
• ワークフローをシンプル(単一責任)に保つ

信頼性

• 適切なタイムアウトを設定
• continue-on-error を戦略的に使用
• 不安定なテストの再試行ロジックを実装
• ワークフロー実行時間を監視
• 古いアーティファクトとキャッシュをクリーンアップ

一般的なパターン

失敗時に PR にコメント

- name: Comment on PR
  if: failure() && github.event_name == 'pull_request'
  uses: actions/github-script@v7
  with:
    script: |
      github.rest.issues.createComment({
        issue_number: context.issue.number,
        owner: context.repo.owner,
        repo: context.repo.repo,
        body: '❌ Tests failed. Please check the workflow logs.'
      })

Dependabot PR を自動マージ

name: Auto-merge Dependabot

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  auto-merge:
    if: github.actor == 'dependabot[bot]'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - run: npm ci
      - run: npm test

      - uses: gh enable-auto-merge --merge
        if: success()
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

デプロイ時に通知

- name: Slack Notification
  if: always()
  uses: 8398a7/action-slack@v3
  with:
    status: ${{ job.status }}
    text: 'Deploy to ${{ inputs.environment }}: ${{ job.status }}'
    webhook_url: ${{ secrets.SLACK_WEBHOOK }}

トラブルシューティング

一般的な問題

ワークフローがトリガーされない:

• ブランチフィルターが実際のブランチ名と一致するか確認
• ワークフローファイルが .github/workflows/ にあるか確認
• YAML 構文が有効か確認

ジョブがスキップされる:

• if 条件を確認
• needs 依存関係が成功したか確認
• ブランチ保護ルールを確認

タイムアウト:

• デフォルトタイムアウトは 360 分
• 明示的なタイムアウトを設定: timeout-minutes: 30
• 長時間実行ステップを最適化

パーミッション拒否:

• ワークフロー権限を更新:

  permissions:
    contents: write
    pull-requests: write
  

シークレットが利用できない:

• シークレット名が完全に一致するか確認(大文字小文字区別)
• シークレットスコープを確認(リポジトリ、組織、環境)
• ワークフローが環境シークレットにアクセス可能か確認

---

ローカルワークフローパターン (自分のリポジトリ)

Python + uv CI (mcp-vector-search)

• uv をインストール: astral-sh/setup-uv@v3 と uv python install 3.11。
• uv sync --dev を使用して uv run ruff, uv run mypy, uv run pytest を実行。
• OS + Python バージョンマトリックスを使用し、linux で Codecov にカバレッジをアップロード。

Node + pnpm CI (ai-code-review)

• pnpm/action-setup@v4 と actions/setup-node@v4 を pnpm キャッシュで使用。
• pnpm install --frozen-lockfile でインストール、その後 pnpm run lint, pnpm run build:types, pnpm test を実行。

タグでリリース

• push タグ v* でトリガー。
• ビルド、GitHub リリースノートを作成、npm または PyPI に公開。
• npm の場合 NODE_AUTH_TOKEN を、PyPI の場合 pypa/gh-action-pypi-publish@release/v1 を使用。

Homebrew 更新パイプライン

• CI 成功後の workflow_run でトリガー。
• HOMEBREW_TAP_TOKEN で scripts/update_homebrew_formula.py を実行。
• 失敗時、手動更新ステップを含む Issue を開く。

リソース

• GitHub Actions Documentation
• Actions Marketplace
• Workflow Syntax Reference
• GitHub Actions Toolkit
• Awesome Actions