writing-github-actions

GitHub Actions の記述

YAML ベースの設定と GitHub とのネイティブな統合を使用して、CI/CD パイプライン、自動テスト、デプロイ、リポジトリ自動化のための GitHub Actions ワークフローを作成します。

目的

GitHub Actions は、GitHub リポジトリ向けのネイティブな CI/CD プラットフォームです。このスキルでは、GitHub Actions に特化したワークフロー構文、トリガー、ジョブのオーケストレーション、再利用可能なパターン、最適化手法、セキュリティプラクティスを扱います。

主な内容：

• ワークフローの YAML 構文と構造
• 再利用可能なワークフローとコンポジットアクション
• マトリックスビルドと並列実行
• キャッシュと最適化戦略
• シークレット管理と OIDC 認証
• 同時実行制御とアーティファクト管理

対象外：

• CI/CD パイプラインの設計戦略 → building-ci-pipelines を参照
• GitOps デプロイパターン → gitops-workflows を参照
• Infrastructure as Code → infrastructure-as-code を参照
• テストフレームワーク → testing-strategies を参照

このスキルを使用するタイミング

次の場合にこのスキルを使用します。

• GitHub リポジトリ用の CI/CD ワークフローを作成するとき
• GitHub Actions を使ってテスト、ビルド、デプロイを自動化するとき
• 複数のリポジトリで再利用可能なワークフローを設定するとき
• キャッシュと並列化によってワークフローのパフォーマンスを最適化するとき
• GitHub Actions のセキュリティに関するベストプラクティスを実装するとき
• GitHub Actions の YAML 構文や動作のトラブルシューティングを行うとき

ワークフローの基礎

基本的なワークフロー構造

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

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

主な構成要素：

• name：ワークフローの表示名
• on：トリガーイベント（push、pull_request、schedule、workflow_dispatch）
• jobs：ジョブの定義（デフォルトでは並列実行）
• runs-on：ランナーの種類（ubuntu-latest、windows-latest、macos-latest）
• steps：順次実行する操作（アクションの使用またはコマンドの実行）

一般的なトリガー

# Code events
on:
  push:
    branches: [main, develop]
    paths: ['src/**']
  pull_request:
    types: [opened, synchronize, reopened]

# Manual trigger
on:
  workflow_dispatch:
    inputs:
      environment:
        type: choice
        options: [dev, staging, production]

# Scheduled
on:
  schedule:
    - cron: '0 2 * * *'  # Daily at 2 AM UTC

トリガーの完全なリファレンスについては、references/triggers-events.md を参照してください。

判断の指針

再利用可能なワークフローとコンポジットアクション

次の場合は再利用可能なワークフローを使用します。

• リポジトリ間で CI/CD ジョブ全体を標準化するとき
• 入力と出力を含めてジョブ全体を置き換える必要があるとき
• シークレットをデフォルトで継承させたいとき
• ジョブレベルの設定で複数のステップをオーケストレーションするとき

次の場合はコンポジットアクションを使用します。

• 5～20 個のステップからなる処理を再利用できるようにパッケージ化するとき
• ジョブ内でステップレベルの抽象化が必要なとき
• Marketplace やプライベートリポジトリを通じて配布したいとき
• アーティファクトを使わずにローカルファイルへアクセスする必要があるとき

機能	再利用可能なワークフロー	コンポジットアクション
スコープ	ジョブ全体	ステップのシーケンス
トリガー	workflow_call	ステップ内の uses:
シークレット	デフォルトで継承	明示的な受け渡しが必要
ファイル共有	アーティファクトが必要	同じランナー／ワークスペース

詳細なパターンについては、references/reusable-workflows.md と references/composite-actions.md を参照してください。

キャッシュ戦略

組み込みのセットアップアクションによるキャッシュを使用します（推奨）：

- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'npm'  # or 'yarn', 'pnpm'

利用可能な対象：Node.js、Python（pip）、Java（maven／gradle）、.NET、Go

次の場合は手動キャッシュを使用します。

• カスタムキャッシュキーが必要なとき
• ビルド出力や標準以外のパスをキャッシュするとき
• 多層キャッシュ戦略を実装するとき

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

最適化手法については、references/caching-strategies.md を参照してください。

セルフホストランナーと GitHub ホストランナー

次の場合は GitHub ホストランナーを使用します。

• 標準的なビルド環境で十分なとき
• プライベートネットワークへのアクセスが不要なとき
• 予算内または無料枠の範囲内であるとき

次の場合はセルフホストランナーを使用します。

• 特定のハードウェア（GPU、ARM、高メモリ）が必要なとき
• プライベートネットワーク／VPN へのアクセスが必要なとき
• 利用量が多いとき（コスト最適化）
• カスタムソフトウェアを事前にインストールしておく必要があるとき

一般的なパターン

依存関係のある複数ジョブのワークフロー

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - run: npm run build
      - uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist/

  test:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v5
        with:
          name: dist
      - run: npm test

  deploy:
    needs: [build, test]
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/download-artifact@v5
      - run: ./deploy.sh

主な要素：

• needs: はジョブの依存関係を作成します（順次実行）
• アーティファクトによってジョブ間でデータを受け渡します
• if: によって条件付き実行が可能になります
• environment: によって保護ルールと環境シークレットを利用できます

マトリックスビルド

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

結果：9 個のジョブ（3 つの OS × 3 つの Node バージョン）

高度なマトリックスパターンについては、examples/matrix-build.yml を参照してください。

同時実行制御

# Cancel in-progress runs on new push
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

# Single deployment per environment
jobs:
  deploy:
    concurrency:
      group: production-deployment
      cancel-in-progress: false
    steps: [...]

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

再利用可能なワークフローの定義

ファイル：.github/workflows/reusable-build.yml

name: Reusable Build
on:
  workflow_call:
    inputs:
      node-version:
        type: string
        default: '20'
    secrets:
      NPM_TOKEN:
        required: false
    outputs:
      artifact-name:
        value: ${{ jobs.build.outputs.artifact }}

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      artifact: build-output
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}
      - run: npm ci && npm run build
      - uses: actions/upload-artifact@v4
        with:
          name: build-output
          path: dist/

再利用可能なワークフローの呼び出し

jobs:
  build:
    uses: ./.github/workflows/reusable-build.yml
    with:
      node-version: '20'
    secrets: inherit  # Same org only

再利用可能なワークフローの詳しいガイドについては、references/reusable-workflows.md を参照してください。

コンポジットアクション

コンポジットアクションの定義

ファイル：.github/actions/setup-project/action.yml

name: 'Setup Project'
description: 'Install dependencies and setup environment'

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

outputs:
  cache-hit:
    value: ${{ steps.cache.outputs.cache-hit }}

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

    - id: cache
      uses: actions/cache@v4
      with:
        path: node_modules
        key: ${{ runner.os }}-deps-${{ hashFiles('**/package-lock.json') }}

    - if: steps.cache.outputs.cache-hit != 'true'
      shell: bash
      run: npm ci

主な要件：

• runs.using: "composite" でアクションの種類を指定します
• すべての run ステップで shell: が必須です
• ${{ inputs.name }} で入力にアクセスします

コンポジットアクションの使用

steps:
  - uses: actions/checkout@v5
  - uses: ./.github/actions/setup-project
    with:
      node-version: '20'
  - run: npm run build

コンポジットアクションの詳しいパターンについては、references/composite-actions.md を参照してください。

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

シークレットの管理

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production  # Uses environment secrets
    steps:
      - env:
          API_KEY: ${{ secrets.API_KEY }}
        run: ./deploy.sh

OIDC 認証（長期間有効な認証情報を使用しない）

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      id-token: write  # Required for OIDC
      contents: read
    steps:
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/GitHubActionsRole
          aws-region: us-east-1
      - run: aws s3 sync ./dist s3://my-bucket

最小限の権限

# Workflow-level
permissions:
  contents: read
  pull-requests: write

# Job-level
jobs:
  deploy:
    permissions:
      contents: write
      deployments: write
    steps: [...]

アクションのバージョン固定

# Pin to commit SHA (not tags)
- uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608  # v5.0.0

Dependabot を有効にする：

ファイル：.github/dependabot.yml

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

包括的なセキュリティガイドについては、references/security-practices.md を参照してください。

最適化の手法

セットアップアクションに組み込まれたキャッシュ（cache: 'npm'）を使用し、依存関係のないジョブは並列実行し、if: による条件付き実行を追加して、チェックアウトの深さ（fetch-depth: 1）を最小限に抑えます。

最適化戦略の詳細については、references/caching-strategies.md を参照してください。

コンテキスト変数

一般的なコンテキスト：github.*、secrets.*、inputs.*、matrix.*、runner.*

- run: echo "Branch: ${{ github.ref }}, Event: ${{ github.event_name }}"

構文の完全なリファレンスについては、references/workflow-syntax.md を参照してください。

段階的な情報開示

詳細なリファレンス

各トピックの詳しい説明については、以下を参照してください。

• references/workflow-syntax.md - YAML 構文の完全なリファレンス
• references/reusable-workflows.md - 再利用可能なワークフローの高度なパターン
• references/composite-actions.md - コンポジットアクションの詳細
• references/caching-strategies.md - 最適化とキャッシュの手法
• references/security-practices.md - 包括的なセキュリティガイド
• references/triggers-events.md - すべてのトリガーの種類とイベントフィルター
• references/marketplace-actions.md - 推奨アクションのカタログ

実用例

すぐに使用できる完全なワークフローテンプレート：

• examples/basic-ci.yml - シンプルな CI ワークフロー
• examples/matrix-build.yml - マトリックス戦略の例
• examples/reusable-deploy.yml - 再利用可能なデプロイワークフロー
• examples/composite-setup/ - コンポジットアクションのテンプレート
• examples/monorepo-workflow.yml - パスフィルターを使用したモノレポ
• examples/security-scan.yml - セキュリティスキャンのワークフロー

検証スクリプト

• scripts/validate-workflow.sh - YAML 構文を検証します

関連スキル

• building-ci-pipelines - CI/CD パイプラインの設計戦略
• gitops-workflows - GitOps デプロイのパターン
• infrastructure-as-code - Terraform/Pulumi との統合
• testing-strategies - テストフレームワークとカバレッジ
• security-hardening - SAST/DAST ツール
• git-workflows - ブランチと PR の理解