Tips - 再利用可能なワークフローとは

GitHub Actionsの再利用可能なワークフロー機能を使うと、ワークフローの定義を一箇所に集約し、複数のリポジトリやプロジェクトから呼び出せるようになります。この記事では、再利用可能なワークフローの作成方法から実践的な活用パターンまでを解説します。

1. 再利用可能なワークフローとは

再利用可能なワークフローは、通常のワークフローファイルと同じYAML形式で記述しますが、onキーにworkflow_callを指定することで、他のワークフローから呼び出せるようになります。これにより、共通のビルド手順やデプロイメントロジックを一箇所で管理できます。

2. 基本的な作成方法

再利用可能なワークフローは.github/workflowsディレクトリに配置します。サブディレクトリはサポートされていない点に注意してください。

2.1 最小限の構成

name: "再利用可能なワークフロー"

on:
  workflow_call:

jobs:
  example_job:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - name: "ビルド処理"
        run: echo "共通のビルド処理を実行"

2.2 入力とシークレットの定義

再利用可能なワークフローに外部から値を渡すには、inputsとsecretsを定義します。これにより、柔軟な設定が可能になります。

重要な制約事項: 環境レベルで定義されたシークレット（environment secrets）は、on.workflow_callではenvironmentキーワードをサポートしていないため、呼び出し元から渡すことができません。再利用可能なワークフロー内のジョブレベルでenvironmentを指定した場合、そこで定義された環境シークレットが使用され、呼び出し元から渡されたシークレットは使用されません。

name: "パラメータ付き再利用可能なワークフロー"

on:
  workflow_call:
    inputs:
      config-path:
        description: "設定ファイルのパス"
        required: true
        type: string
      environment:
        description: "デプロイ環境"
        required: false
        type: string
        default: "production"
    secrets:
      deploy_token:
        description: "デプロイ用トークン"
        required: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - name: "設定を使用したデプロイ"
        run: |
          echo "環境: ${{ inputs.environment }}"
          echo "設定パス: ${{ inputs.config-path }}"
        env:
          TOKEN: ${{ secrets.deploy_token }}

inputsで定義できる型はboolean、number、stringの3種類です。

3. ワークフローの呼び出し方法

再利用可能なワークフローを呼び出すには、usesキーワードを使用します。アクションの呼び出しと異なり、ジョブレベルで直接指定します。

3.1 参照方法

再利用可能なワークフローは以下の構文で参照できます。

1. 他のリポジトリから参照: {owner}/{repo}/.github/workflows/{filename}@{ref}
2. 同じリポジトリ内: ./.github/workflows/{filename}

{ref}にはSHA、リリースタグ、ブランチ名を指定できます。安定性とセキュリティの観点からは、コミットSHAの使用が最も安全です。

3.2 実際の呼び出し例

name: "ワークフロー呼び出しの例"

on:
  pull_request:
    branches:
      - main

jobs:
  call-workflow-1:
    uses: tanaka-org/shared-workflows/.github/workflows/build.yml@v1

  call-workflow-2:
    uses: ./.github/workflows/test.yml

  call-workflow-with-params:
    permissions:
      contents: read
      pull-requests: write
    uses: tanaka-org/shared-workflows/.github/workflows/deploy.yml@main
    with:
      config-path: .github/config.yml
      environment: staging
    secrets:
      deploy_token: ${{ secrets.DEPLOY_TOKEN }}

3.3 シークレットの継承

同じ組織やエンタープライズ内でワークフローを呼び出す場合、secrets: inheritを使用してすべてのシークレットを暗黙的に渡せます。

jobs:
  call-workflow:
    uses: tanaka-org/shared-workflows/.github/workflows/deploy.yml@main
    with:
      config-path: .github/config.yml
    secrets: inherit

シークレット継承の補足: secrets: inheritを使用すると、呼び出し元のワークフローで利用可能なすべてのシークレットが、再利用可能なワークフローに渡されます。再利用可能なワークフロー側でonキーに明示的に定義されていないシークレットでも参照できます。

4. 実践的な活用パターン

4.1 Matrix戦略との組み合わせ

Matrix戦略を使用すると、異なるパラメータで同じワークフローを複数回実行できます。これは環境ごとのデプロイなどに便利です。

jobs:
  deploy-to-environments:
    strategy:
      matrix:
        target: [dev, staging, production]
    uses: tanaka-org/shared-workflows/.github/workflows/deploy.yml@main
    with:
      target: ${{ matrix.target }}

この例では、dev、staging、productionの3つの環境に対して、それぞれデプロイジョブが実行されます。

4.2 ワークフローのネスト

再利用可能なワークフローから、さらに別の再利用可能なワークフローを呼び出せます。最大10レベルまでの階層をサポートしていますが、ループは許可されていません。

name: "レベル1のワークフロー"

on:
  workflow_call:

jobs:
  call-level-2:
    uses: tanaka-org/shared-workflows/.github/workflows/level-2.yml@v1

ネストされたワークフローでは、すべてのワークフローが呼び出し元からアクセス可能である必要があり、権限はチェーン全体で維持または縮小されますが、昇格はできません。

4.2.1 シークレットのネスト時の注意点

シークレットは直接呼び出されるワークフローにのみ渡されます。例えば、ワークフローA → B → Cという連鎖では、AからCにシークレットを渡すには、A → BとB → Cの両方でシークレットを明示的に渡す必要があります。

# ワークフローA
jobs:
  call-workflow-b:
    uses: tanaka-org/workflows/.github/workflows/b.yml@main
    secrets: inherit  # すべてのシークレットをBに渡す

# ワークフローB
jobs:
  call-workflow-c:
    uses: yamada-org/workflows/.github/workflows/c.yml@main
    secrets:
      api_token: ${{ secrets.api_token }}  # 特定のシークレットのみCに渡す

4.3 出力の活用

再利用可能なワークフローから値を返すには、出力を定義します。出力はステップレベル → ジョブレベル → ワークフローレベルの順にマッピングします。

重要: 出力の値は、再利用可能なワークフロー内のジョブレベルの出力の値に設定する必要があります。ステップレベルの出力を直接ワークフローレベルにマッピングすることはできません。以下の例のように、必ずジョブレベルの出力を経由してください。

name: "出力を返すワークフロー"

on:
  workflow_call:
    outputs:
      build_version:
        description: "ビルドされたバージョン番号"
        value: ${{ jobs.build_job.outputs.version }}
      artifact_url:
        description: "成果物のURL"
        value: ${{ jobs.build_job.outputs.url }}

jobs:
  build_job:
    name: "ビルド処理"
    runs-on: ubuntu-latest
    outputs:
      version: ${{ steps.version_step.outputs.version }}
      url: ${{ steps.upload_step.outputs.url }}
    steps:
      - id: version_step
        run: echo "version=1.2.3" >> $GITHUB_OUTPUT
      - id: upload_step
        run: echo "url=https://example.com/artifact.zip" >> $GITHUB_OUTPUT

呼び出し側では、needsコンテキストを使って出力にアクセスします。

name: "出力を使用するワークフロー"

on:
  workflow_dispatch:

jobs:
  build:
    uses: tanaka-org/shared-workflows/.github/workflows/build.yml@v1

  notify:
    runs-on: ubuntu-latest
    needs: build
    steps:
      - run: |
          echo "ビルドバージョン: ${{ needs.build.outputs.build_version }}"
          echo "成果物URL: ${{ needs.build.outputs.artifact_url }}"

ジョブの出力を参照する場合と同じ方法で、再利用可能なワークフローの出力にアクセスできます。

5. 組織内での共有とテンプレート化

5.1 ワークフローテンプレートの作成

組織内でワークフローテンプレートを提供することで、チームメンバーが簡単に新しいワークフローを作成できます。

1. 組織に.githubという名前のリポジトリを作成（存在しない場合）
2. workflow-templatesディレクトリを作成
3. ワークフローファイルを作成

# workflow-templates/ci-workflow.yml
name: "組織のCIワークフロー"

on:
  push:
    branches: [ $default-branch ]
  pull_request:
    branches: [ $default-branch ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - name: "ビルド処理"
        run: echo "組織標準のビルド処理"

$default-branchプレースホルダーは、ワークフロー作成時に自動的にリポジトリのデフォルトブランチ名に置き換えられます。

1. メタデータファイルを作成

{
    "name": "組織標準CIワークフロー",
    "description": "組織で推奨されるCI/CDパイプライン",
    "iconName": "ci-icon",
    "categories": [
        "Go",
        "Continuous integration"
    ],
    "filePatterns": [
        "go.mod$",
        "^Dockerfile",
        ".*\\.go$"
    ]
}

メタデータファイルの主要なフィールド:

• name: 必須。ワークフロー一覧に表示される名前
• description: 必須。ワークフローの説明
• iconName: 任意。SVGファイル名またはOcticonアイコン名（例: octicon smiley）
• categories: 任意。ワークフローが表示されるカテゴリ
• filePatterns: 任意。正規表現でマッチするファイルがある場合にワークフローを提案

5.2 プライベートリポジトリからの共有

プライベートリポジトリのアクションやワークフローを共有する手順:

1. GitHubでプライベートリポジトリに移動
2. Settings → Actions → Generalを開く
3. Accessセクションで適切なアクセス範囲を選択:
   • Accessible from repositories owned by 'USERNAME' user: 自分の他のリポジトリからアクセス可能
   • Accessible from repositories in the 'ORGANIZATION-NAME' organization: 組織内のリポジトリからアクセス可能
4. Saveをクリック

5.3 セキュリティ上の注意事項

プライベートリポジトリを共有する際の重要な考慮事項:

• 外部コラボレーターが、直接アクセス権を持たないプライベートリポジトリに間接的にアクセスできます
• ワークフロー実行時のログを通じて、プライベートリポジトリの情報が見える可能性があります
• GitHubはランナーにスコープ付きインストールトークンを渡し、これは読み取りアクセス権を持ち、1時間後に自動的に失効します

6. 実用的なワークフロー構成例

複数の再利用可能なワークフローを組み合わせた実践的な例を紹介します。

name: "本番環境へのデプロイパイプライン"

on:
  push:
    branches:
      - main

jobs:
  lint:
    uses: ./.github/workflows/lint.yml

  test:
    needs: lint
    strategy:
      matrix:
        test-type: [unit, integration, e2e]
    uses: ./.github/workflows/test.yml
    with:
      test-type: ${{ matrix.test-type }}

  build:
    needs: test
    uses: ./.github/workflows/build.yml
    secrets: inherit

  deploy-staging:
    needs: build
    uses: tanaka-org/shared-workflows/.github/workflows/deploy.yml@v1
    with:
      environment: staging
      version: ${{ needs.build.outputs.build_version }}
    secrets:
      deploy_token: ${{ secrets.STAGING_DEPLOY_TOKEN }}

  deploy-production:
    needs: deploy-staging
    uses: tanaka-org/shared-workflows/.github/workflows/deploy.yml@v1
    with:
      environment: production
      version: ${{ needs.build.outputs.build_version }}
    secrets:
      deploy_token: ${{ secrets.PRODUCTION_DEPLOY_TOKEN }}

この構成により、以下のフローが実現されます:

7. まとめ

再利用可能なワークフローは、GitHub Actionsの強力な機能です。適切に活用することで、以下のメリットが得られます:

• 保守性の向上: ワークフローのロジックを一箇所で管理
• 一貫性の確保: 組織全体で統一されたCI/CDプロセス
• 開発効率の向上: 定型的なワークフローの記述が不要に
• 変更の容易さ: 共通部分の修正が一度で完了

組織やチームで標準化されたワークフローを定義し、各プロジェクトから呼び出す形にすることで、CI/CDパイプラインの品質と効率を大きく改善できます。まずは小さなワークフローから始めて、徐々に再利用可能な部分を抽出していくアプローチをお勧めします。