GitHub Actions 完全ガイド【2026年最新】｜workflow 構文・Matrix・Secrets・OIDC・Environments・Concurrency・Reusable Workflows・Artifacts v4・Custom Runner Images までを実戦パターンで解説

name: CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v5
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm test

on:
  # コードの push（ブランチ・パス・タグフィルタ）
  push:
    branches: [main, "release/**"]
    branches-ignore: [gh-pages]
    paths: ["src/**", "package.json"]
    paths-ignore: ["**.md"]
    tags: ["v*.*.*"]

  # Pull Request（どのアクションで走るか細かく指定）
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]
    branches: [main]

  # 手動実行（入力フォーム付き）
  workflow_dispatch:
    inputs:
      environment:
        description: "デプロイ先"
        required: true
        default: staging
        type: choice
        options: [staging, production]
      dry_run:
        type: boolean
        default: true

  # スケジュール（cron）
  schedule:
    - cron: "0 3 * * *"     # 毎日 03:00 UTC

  # 他ワークフローの完了をトリガーに
  workflow_run:
    workflows: [CI]
    types: [completed]
    branches: [main]

  # Issue / PR コメント・ラベル変更など
  issues:
    types: [opened, labeled]
  issue_comment:
    types: [created]

  # 外部トリガー（REST API / GitHub Apps）
  repository_dispatch:
    types: [deploy-prod]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - run: npm ci
      - run: npm run lint

  test:
    runs-on: ubuntu-latest
    needs: lint                             # lint が成功したらだけ走る
    timeout-minutes: 15                     # 15 分で強制終了
    env:
      CI: true
      NODE_ENV: test
    steps:
      - uses: actions/checkout@v5
      - run: npm ci
      - run: npm test -- --coverage
      - name: カバレッジ閾値チェック
        if: always()                        # test 失敗でも実行
        run: |
          node scripts/check-coverage.mjs

  build:
    runs-on: ubuntu-latest
    needs: [lint, test]                     # 両方成功後に並列実行可能
    if: github.ref == 'refs/heads/main'     # main だけ
    steps:
      - uses: actions/checkout@v5
      - run: npm ci
      - run: npm run build

steps:
  - name: テスト
    id: test-step
    run: npm test
    continue-on-error: true       # 失敗しても次に進む

  - name: 失敗時のみ通知
    if: failure() && steps.test-step.outcome == 'failure'
    run: ./scripts/notify-slack.sh

  - name: 成功時のみアーティファクト収集
    if: success()
    uses: actions/upload-artifact@v4
    with: { name: report, path: coverage/ }

  - name: どんな結果でも実行（cleanup）
    if: always()
    run: rm -rf /tmp/build-cache

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false                     # ある組合せが失敗しても他を続行
      max-parallel: 6
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        node: [20, 22, 24]
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v5
        with: { node-version: "${{ matrix.node }}", cache: npm }
      - run: npm ci
      - run: npm test

strategy:
  matrix:
    os: [ubuntu-latest, macos-latest]
    node: [20, 22, 24]
    include:
      # Windows は Node 22 だけ追加で試す
      - os: windows-latest
        node: 22
        extra-flag: --no-color
      # ubuntu + node 24 のときだけ追加の環境変数
      - os: ubuntu-latest
        node: 24
        db: postgres-17
    exclude:
      # macOS + node 20 は除外
      - os: macos-latest
        node: 20

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production              # environment secrets / protection rule が効く
    env:
      # Variables（機密でない設定値。Settings > Actions > Variables）
      API_BASE: ${{ vars.API_BASE }}
      REGION:   ${{ vars.AWS_REGION }}
    steps:
      - uses: actions/checkout@v5

      - name: デプロイ
        env:
          # Secrets（暗号化、ログマスクあり）
          DATABASE_URL: ${{ secrets.DATABASE_URL }}
          SLACK_TOKEN:  ${{ secrets.SLACK_WEBHOOK }}
        run: ./scripts/deploy.sh

permissions:
  id-token: write              # OIDC トークン発行に必須
  contents: read

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

      - uses: aws-actions/configure-aws-credentials@v5
        with:
          role-to-assume: arn:aws:iam::123456789012:role/gh-deploy
          aws-region: ap-northeast-1

      # この時点で aws CLI / SDK が使える（期限付き STS 認証情報）
      - run: aws s3 sync ./dist s3://my-bucket/

jobs:
  deploy-staging:
    runs-on: ubuntu-latest
    environment:
      name: staging
      url: https://staging.example.com

    steps:
      - run: ./deploy.sh

  deploy-production:
    runs-on: ubuntu-latest
    needs: deploy-staging
    environment:
      name: production                 # 承認者設定・待機時間・ブランチ制限が効く
      url: https://example.com

    steps:
      - run: ./deploy.sh

# PR に対して新しい push が来たら古いジョブをキャンセル
concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true

# デプロイは直列（cancel しない、順次キューイング）
jobs:
  deploy:
    concurrency:
      group: deploy-${{ github.ref }}
      cancel-in-progress: false    # デプロイ途中でキャンセルすると壊れるため
    runs-on: ubuntu-latest
    steps:
      - run: ./deploy.sh

# デフォルトを最小に
permissions:
  contents: read

jobs:
  test:
    runs-on: ubuntu-latest
    # test は読むだけでいい（contents: read のまま）
    steps:
      - uses: actions/checkout@v5
      - run: npm test

  release:
    runs-on: ubuntu-latest
    # リリースでタグを打つ時だけ書込権限を付与
    permissions:
      contents: write        # タグ push に必要
      id-token: write        # OIDC 発行（パッケージ署名等）
    steps:
      - uses: actions/checkout@v5
      - run: npm version patch && git push --tags

steps:
  - uses: actions/checkout@v5

  # Node + npm
  - uses: actions/setup-node@v5
    with:
      node-version: 22
      cache: npm                       # package-lock.json から自動でキー生成
      cache-dependency-path: "**/package-lock.json"   # monorepo

  # Python + pip
  - uses: actions/setup-python@v5
    with:
      python-version: "3.12"
      cache: pip

  # Bun
  - uses: oven-sh/setup-bun@v2
    with: { bun-version: 1.3 }

  # Deno（setup-deno は cache を明示）
  - uses: denoland/setup-deno@v2
    with: { deno-version: v2.7.x }

- uses: actions/cache@v5
  with:
    path: |
      ~/.cache/puppeteer
      ~/.cache/next
      .next/cache
    key: ${{ runner.os }}-next-${{ hashFiles('package-lock.json') }}-${{ hashFiles('**/*.ts', '**/*.tsx') }}
    restore-keys: |
      ${{ runner.os }}-next-${{ hashFiles('package-lock.json') }}-
      ${{ runner.os }}-next-

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - run: npm ci && npm run build
      - uses: actions/upload-artifact@v4
        with:
          name: dist-${{ matrix.os }}-${{ matrix.node }}   # 一意にする
          path: dist/
          retention-days: 7
          compression-level: 6                 # 0=無圧縮 ... 9=最大
          if-no-files-found: error

  release:
    runs-on: ubuntu-latest
    needs: build
    steps:
      - uses: actions/download-artifact@v4
        with:
          pattern: dist-*                      # 複数の artifact をまとめて DL
          merge-multiple: true
          path: all-dists/
      - run: ls -la all-dists/

name: Reusable Deploy

on:
  workflow_call:
    inputs:
      environment:
        type: string
        required: true
      node-version:
        type: string
        default: "22"
    secrets:
      DATABASE_URL:
        required: true
    outputs:
      url:
        description: デプロイ先 URL
        value: ${{ jobs.deploy.outputs.url }}

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: ${{ inputs.environment }}
    outputs:
      url: ${{ steps.do-deploy.outputs.url }}
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v5
        with: { node-version: "${{ inputs.node-version }}", cache: npm }
      - id: do-deploy
        env: { DATABASE_URL: "${{ secrets.DATABASE_URL }}" }
        run: |
          ./scripts/deploy.sh
          echo "url=https://${{ inputs.environment }}.example.com" >> $GITHUB_OUTPUT

name: Release

on:
  push:
    branches: [main]

jobs:
  stg:
    uses: ./.github/workflows/reusable-deploy.yml
    with:
      environment: staging
    secrets:
      DATABASE_URL: ${{ secrets.STAGING_DB_URL }}

  prod:
    needs: stg
    uses: ./.github/workflows/reusable-deploy.yml
    with:
      environment: production
    secrets:
      DATABASE_URL: ${{ secrets.PROD_DB_URL }}

  notify:
    needs: [stg, prod]
    runs-on: ubuntu-latest
    steps:
      - run: echo "stg=${{ needs.stg.outputs.url }} prod=${{ needs.prod.outputs.url }}"

name: Setup App
description: Checkout + Node + 依存インストール + キャッシュの決まり切った一連処理

inputs:
  node-version:
    default: "22"
  frozen:
    default: "true"

runs:
  using: composite
  steps:
    - uses: actions/checkout@v5

    - uses: actions/setup-node@v5
      with: { node-version: "${{ inputs.node-version }}", cache: npm }

    - if: inputs.frozen == 'true'
      shell: bash
      run: npm ci

    - if: inputs.frozen != 'true'
      shell: bash
      run: npm install

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: ./.github/actions/setup-app
        with: { node-version: 22 }
      - run: npm test

jobs:
  build:
    runs-on:
      group: my-custom-pool
      labels: [ubuntu-24.04, prebuilt-cxx, node-22]     # 事前にイメージに焼いた label
    steps:
      # apt-get install も npm install も最小限に
      - uses: actions/checkout@v5
      - run: npm run build

steps:
  - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v5.0.0
  - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020  # v5.0.0
  # ファーストパーティ（actions/*）は @v5 でも許容範囲だが、
  # サードパーティのアクションは SHA 必須にするのが 2026 年の標準

name: Vercel Deploy
on:
  push:
    branches: [main]
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - 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: ${{ github.ref == 'refs/heads/main' && '--prod' || '' }}

name: Cloudflare
on: { push: { branches: [main] } }

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions: { contents: read, id-token: write }
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v5
        with: { node-version: 22, cache: npm }
      - run: npm ci && npm run build
      - uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

name: Docker
on:
  push:
    branches: [main]
    tags: ["v*.*.*"]

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write              # GHCR に push するのに必要
      id-token: write              # 署名用（cosign 連携）
    steps:
      - uses: actions/checkout@v5
      - uses: docker/setup-buildx-action@v3
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - uses: docker/metadata-action@v5
        id: meta
        with:
          images: ghcr.io/${{ github.repository }}
      - uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max
          platforms: linux/amd64,linux/arm64

permissions:
  id-token: write
  contents: read

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

      - uses: aws-actions/configure-aws-credentials@v5
        with:
          role-to-assume: arn:aws:iam::123456789012:role/gh-actions
          aws-region: ap-northeast-1

      - uses: aws-actions/amazon-ecr-login@v2
        id: login-ecr

      - run: |
          docker build -t $ECR_REGISTRY/app:${{ github.sha }} .
          docker push   $ECR_REGISTRY/app:${{ github.sha }}
        env:
          ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }}

      - uses: aws-actions/amazon-ecs-deploy-task-definition@v2
        with:
          task-definition: infra/task-def.json
          service: prod-app
          cluster: prod-cluster
          wait-for-service-stability: true