GitHub Actions Reusable Workflows入門：再利用の基本

GitHub Actionsで複数リポジトリを管理していると、同じようなワークフローをコピー＆ペーストする場面が出てきます。

Reusable Workflows（再利用可能なワークフロー）を使えば、ワークフローを一箇所で管理し、他のリポジトリから呼び出せます。

この記事では、GitHubの公式ドキュメントを参照しながら、Reusable Workflowsの基本から実践的な使い方までを解説します。

Reusable Workflowsとは

Reusable Workflowsは、他のワークフローから呼び出せるワークフローです。

通常のワークフローと同様に.github/workflows/に配置しますが、workflow_callトリガーを持つことで、他のワークフローから「部品」として利用できます。

用語

用語意味
Caller Workflow呼び出す側のワークフロー
Called Workflow（Reusable Workflow）呼び出される側のワークフロー

基本的な構文

Reusable Workflow側（呼び出される側）

on: workflow_callを指定することで、他のワークフローから呼び出し可能になります。

# .github/workflows/build.yml
name: Build

on:
  workflow_call:  # これがポイント

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

Caller Workflow側（呼び出す側）

usesキーワードでReusable Workflowを指定します。

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

on:
  push:
    branches: [main]

jobs:
  call-build:
    uses: ./.github/workflows/build.yml  # 同一リポジトリ内

他のリポジトリからの呼び出し

Reusable Workflowsの真価は、リポジトリを跨いで呼び出せる点にあります。

構文

uses: {owner}/{repo}/.github/workflows/{filename}@{ref}
  • {owner}: リポジトリのオーナー（ユーザー名 or Organization名）
  • {repo}: リポジトリ名
  • {filename}: ワークフローファイル名
  • {ref}: ブランチ名、タグ、またはコミットSHA

例

jobs:
  build:
    uses: hasegawa496/.github/.github/workflows/build.yml@main

refの指定方法

指定方法例特徴
ブランチ名@main常に最新。破壊的変更のリスクあり
タグ@v1.0.0バージョン固定。安定運用向け
SHA@a1b2c3d...完全固定。セキュリティ重視

公式ドキュメントによると、同名のタグとブランチがある場合はタグが優先されます。

公開範囲とアクセス制御

パブリックリポジトリ

パブリックリポジトリに配置したReusable Workflowは、誰でも呼び出し可能です。

hasegawa496/.github (PUBLIC)
└── .github/workflows/build.yml  ← 誰でも使える

プライベートリポジトリ

プライベートリポジトリのReusable Workflowは、デフォルトでは外部から呼び出せません。

同一オーナー（または同一Organization）のリポジトリ間で共有するには、リポジトリ設定で許可が必要です。

Settings > Actions > General > Access で設定:

  • 「Accessible from repositories in the ‘{owner}’ organization」を選択
hasegawa496/shared-workflows (PRIVATE)
└── .github/workflows/build.yml  ← 設定次第で同一オーナーのリポジトリから呼び出し可能

inputs：入力パラメータ

呼び出し時にパラメータを渡せます。

Reusable Workflow側

on:
  workflow_call:
    inputs:
      node-version:
        description: 'Node.jsのバージョン'
        required: false
        type: string
        default: '20'
      environment:
        description: 'デプロイ環境'
        required: true
        type: string

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}
      - run: echo "Environment: ${{ inputs.environment }}"

Caller Workflow側

jobs:
  deploy:
    uses: hasegawa496/.github/.github/workflows/deploy.yml@main
    with:
      node-version: '22'
      environment: 'production'

入力の型

型例
string'production'
booleantrue / false
number20

secrets：シークレットの受け渡し

APIトークンなどのシークレットを渡す方法は2つあります。

方法1: 明示的に渡す

# Reusable Workflow側
on:
  workflow_call:
    secrets:
      deploy-token:
        description: 'デプロイ用トークン'
        required: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - run: echo "Token: ${{ secrets.deploy-token }}"
# Caller Workflow側
jobs:
  deploy:
    uses: hasegawa496/.github/.github/workflows/deploy.yml@main
    secrets:
      deploy-token: ${{ secrets.DEPLOY_TOKEN }}

方法2: inherit で一括継承

すべてのシークレットを継承する場合はsecrets: inheritを使用します。

jobs:
  deploy:
    uses: hasegawa496/.github/.github/workflows/deploy.yml@main
    secrets: inherit  # Caller Workflowのシークレットをすべて継承

この場合、Reusable Workflow側でsecrets:の定義がなくても、Caller側のシークレットを${{ secrets.DEPLOY_TOKEN }}で参照できます。

outputs：出力の取得

Reusable Workflowから値を返すことも可能です。

Reusable Workflow側

on:
  workflow_call:
    outputs:
      artifact-url:
        description: 'ビルド成果物のURL'
        value: ${{ jobs.build.outputs.url }}

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      url: ${{ steps.upload.outputs.artifact-url }}
    steps:
      - id: upload
        run: echo "artifact-url=https://example.com/artifact.zip" >> $GITHUB_OUTPUT

Caller Workflow側

jobs:
  build:
    uses: hasegawa496/.github/.github/workflows/build.yml@main

  notify:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - run: echo "Artifact URL: ${{ needs.build.outputs.artifact-url }}"

出力はstep → job → workflowの順で伝播させる必要がある点に注意が必要です。

制限事項

公式ドキュメントに記載されている主な制限は以下の通りです。

制限内容
ネストの深さ最大10レベル（Caller + 9レベルのReusable Workflow）
呼び出し数1つのワークフローファイルから最大50個のユニークなReusable Workflow
ループ禁止ワークフローの循環参照は不可
環境シークレットCaller側の環境シークレットはReusable Workflowに渡せない

他の再利用方法との比較

GitHub Actionsには、Reusable Workflows以外にも再利用の仕組みがあります。

方法単位用途
Reusable Workflowsワークフロー全体CI/CDパイプライン全体の共通化
Composite Actionsステップの集合複数ステップをまとめて再利用
JavaScript/Docker Actions単一アクション複雑なロジックをカプセル化

使い分けの目安

  • ビルド〜テスト〜デプロイの一連の流れを共通化したい → Reusable Workflows
  • 特定の処理（セットアップ、通知など）を共通化したい → Composite Actions
  • 複雑なロジックや外部API連携 → JavaScript/Docker Actions

実践例：ラベル同期ワークフロー

別記事で紹介している.githubリポジトリでの活用例です。

Reusable Workflow（共通処理）

# hasegawa496/.github/.github/workflows/sync-labels.yml
name: Sync Labels

on:
  workflow_call:

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout .github repository
        uses: actions/checkout@v4
        with:
          repository: hasegawa496/.github
          path: .github-repo

      - name: Sync labels
        uses: EndBug/label-sync@v2
        with:
          config-file: .github-repo/.github/labels.yml
          delete-other-labels: false

Caller Workflow（各リポジトリに配置）

# 各リポジトリの .github/workflows/sync-labels.yml
name: Sync Labels

on:
  workflow_dispatch:  # 手動実行

jobs:
  sync:
    uses: hasegawa496/.github/.github/workflows/sync-labels.yml@main
    secrets: inherit

これにより、ラベル定義の変更は.githubリポジトリで一度行えば、各リポジトリで手動実行するだけで同期できます。

まとめ

ポイント内容
トリガーon: workflow_call
呼び出し構文uses: {owner}/{repo}/.github/workflows/{file}@{ref}
パラメータ渡しinputs（値）、secrets（機密情報）
結果の取得outputs
公開範囲パブリックなら誰でも、プライベートは設定次第

Reusable Workflowsを活用することで、ワークフローの重複を減らし、保守性を高められます。

特に複数リポジトリを管理している場合は、共通処理を一箇所にまとめることで、変更時の影響範囲を限定できる点が大きなメリットです。

参考リンク