GitHub Actions再利用可能ワークフロー｜compositeとの違い

再利用可能ワークフローは、on: workflow_call を書いたワークフローを、別のワークフローの「ジョブ」として呼び出す仕組みです。 複数のジョブ・ランナーごとまとめて使い回したいときは再利用可能ワークフロー、ジョブの中の「ステップ」をまとめたいときは composite action を使います。

# 呼び出される側：.github/workflows/reusable-test.yml
on:
  workflow_call:
    inputs:
      node-version:
        type: string
        default: "22"
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: ${{ inputs.node-version }}
      - run: npm ci && npm test

# 呼び出す側：.github/workflows/ci.yml
on: [pull_request]
jobs:
  test:
    uses: ./.github/workflows/reusable-test.yml   # steps ではなく jobs の直下に書く
    with:
      node-version: "24"

確認環境：この記事の YAML は actionlint 1.7.12（GitHub リリースのバイナリ）と check-jsonschema 0.38.2（SchemaStore のスキーマ）で検査し、検出されたエラー文をそのまま載せています。入れ子の上限・権限・secrets の決まりは GitHub Docs と GitHub Changelog（2025年11月6日）で確かめています。アクションの版（actions/checkout v7.0.1・actions/setup-node v7.1.0）は git ls-remote でタグを確かめました（確認日 2026年10月13日）。

再利用可能ワークフローの書き方

呼び出される側（workflow_call）

on.workflow_call の下に、受け取る値（inputs）・秘密情報（secrets）・返す値（outputs）を書きます。

# .github/workflows/reusable-test.yml
name: reusable-test

on:
  workflow_call:
    inputs:
      node-version:
        description: 使う Node.js の版
        type: string
        default: "22"
      run-e2e:
        type: boolean
        default: false
      shard-count:
        type: number
        default: 1
    secrets:
      NPM_TOKEN:
        required: false
    outputs:
      coverage:
        description: 行カバレッジ（%）
        value: ${{ jobs.test.outputs.coverage }}

permissions:
  contents: read

jobs:
  test:
    runs-on: ubuntu-latest
    outputs:
      coverage: ${{ steps.cov.outputs.pct }}
    steps:
      - uses: actions/checkout@v7
      - uses: ./.github/actions/setup-node-deps
        with:
          node-version: ${{ inputs.node-version }}
          npm-token: ${{ secrets.NPM_TOKEN }}
      - run: npm test -- --coverage
      - id: cov
        run: echo "pct=87.5" >> "$GITHUB_OUTPUT"
      - if: ${{ inputs.run-e2e }}
        run: npm run e2e -- --shard-count=${{ inputs.shard-count }}

ファイルは .github/workflows/ の直下に置きます。 GitHub Docs には「Subdirectories of the workflows directory are not supported.」とあります。

呼び出す側

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

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  test:
    strategy:
      fail-fast: false
      matrix:
        node: ["22", "24"]
    uses: ./.github/workflows/reusable-test.yml
    with:
      node-version: ${{ matrix.node }}
      run-e2e: ${{ github.event_name == 'push' }}
    secrets:
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

  report:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - run: echo "coverage=${{ needs.test.outputs.coverage }}"

呼び出すジョブには runs-on も steps も書きません。 GitHub Docs で呼び出すジョブに書けるとされているキーは次の通りです。

matrix で呼んだときの outputs は、値を設定した最後の成功した実行の値になります（GitHub Docs）。matrix の行ごとの値を集めたいときは、行ごとに名前を変えた artifact に書き出す方法があります。

uses の書き方

uses には ${{ }} の式を書けません。 GitHub Docs には「You cannot use contexts or expressions in this keyword.」とあります。

secrets の渡し方と secrets: inherit

secrets は、直接呼び出したワークフローにだけ渡ります。 GitHub Docs には「Secrets are only passed to directly called workflow.」とあり、A → B → C と呼ぶとき、C で使う secrets は B が改めて渡す必要があります。

環境（environment）の secrets は、呼び出し側からは渡せません。 呼び出すジョブには environment を書けず、呼び出される側のジョブに environment を書いてその secrets を読みます。同じ名前の secrets があるときは environment の secrets が使われます。

env も引き継がれません。GitHub Docs の決まりです。

入れ子（ネスト）と上限

再利用可能ワークフローは、呼び出し元を含めて10段までつなげられます。 2025年11月6日の GitHub Changelog で、4段から10段、呼び出せる数が20から50に引き上げられました。

GitHub Enterprise Server では版によって上限が異なるので、使っている版の Docs を見ます。

入れ子のコピペ例：ci → release → deploy

# ci.yml の jobs に足す
  release:
    if: github.ref == 'refs/heads/main'
    needs: test
    permissions:
      contents: read
      id-token: write
    uses: ./.github/workflows/reusable-release.yml
    with:
      environment: production
    secrets: inherit

# .github/workflows/reusable-release.yml（2段目）
name: reusable-release

on:
  workflow_call:
    inputs:
      environment:
        type: string
        required: true

jobs:
  deploy:
    permissions:
      contents: read
      id-token: write
    uses: ./.github/workflows/reusable-deploy.yml
    with:
      environment: ${{ inputs.environment }}
    secrets:
      SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}   # 3段目へは改めて渡す

# .github/workflows/reusable-deploy.yml（3段目）
name: reusable-deploy

on:
  workflow_call:
    inputs:
      environment:
        type: string
        required: true
    secrets:
      SLACK_WEBHOOK_URL:
        required: true
    outputs:
      url:
        value: ${{ jobs.deploy.outputs.url }}

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: ${{ inputs.environment }}
    permissions:
      contents: read
      id-token: write
    outputs:
      url: ${{ steps.deploy.outputs.url }}
    steps:
      - uses: actions/checkout@v7
      - id: deploy
        run: echo "url=https://example.com" >> "$GITHUB_OUTPUT"
      - name: 通知
        env:
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
        run: |
          curl -fsS -X POST -H 'Content-Type: application/json' \
            -d "{\"text\":\"deployed ${{ inputs.environment }}\"}" "$SLACK_WEBHOOK_URL"

この記事の4つのワークフローと composite action を actionlint 1.7.12 で検査した結果です。

actionlint
echo $?
# 0（指摘なし）

権限（permissions）の受け渡し

呼び出される側は、呼び出し元から受け取った GITHUB_TOKEN の権限を「同じか、狭く」しかできません。 GitHub Docs の決まりです。

広い権限を求めたときのエラーは、次の形です（実際に報告された文面）。

The nested job 'message-check' is requesting 'pull-requests: read', but is only allowed 'pull-requests: none'.

直し方は、呼び出す側のジョブで先に権限を与えることです。 上の入れ子の例で ci.yml の release ジョブに id-token: write を書いているのは、3段目で OIDC のトークンを取るためです。なお、この「広げられない」誤りは actionlint 1.7.12 では検出されませんでした（3段目を contents: write にしても指摘なし）。

OIDC で AWS に入る設定は、関連記事「GitHub ActionsからOIDCでAWSへ｜IAMロールの信頼ポリシー」で扱っています。再利用可能ワークフローから OIDC を使うと、トークンの job_workflow_ref に呼び出された側のワークフローのパスと ref が入ります。

composite action の書き方

composite action は、複数のステップを1つのステップとしてまとめたものです。 呼び出し元のジョブと同じランナーで動き、チェックアウトしたファイルや環境もそのまま使えます。

# .github/actions/setup-node-deps/action.yml
name: setup-node-deps
description: Node.js を入れて npm ci する
inputs:
  node-version:
    description: Node.js の版
    required: false
    default: "22"
  npm-token:
    description: private パッケージ用のトークン
    required: false
    default: ""
outputs:
  cache-hit:
    description: キャッシュが当たったか
    value: ${{ steps.node.outputs.cache-hit }}
runs:
  using: composite
  steps:
    - id: node
      uses: actions/setup-node@v7
      with:
        node-version: ${{ inputs.node-version }}
        cache: npm
    - run: npm ci
      shell: bash
      env:
        NODE_AUTH_TOKEN: ${{ inputs.npm-token }}

# 呼び出す側（ステップとして使う）
    steps:
      - uses: actions/checkout@v7          # ローカルの action を使う前にチェックアウトが要る
      - id: deps
        uses: ./.github/actions/setup-node-deps
        with:
          node-version: "24"
          npm-token: ${{ secrets.NPM_TOKEN }}   # secrets は inputs で渡す
      - run: echo "cache-hit=${{ steps.deps.outputs.cache-hit }}"

actionlint は action.yml の中身を検査しません。 action.yml を渡すと "jobs" section is missing in workflow となりました。呼び出し側の inputs の誤りは actionlint が見つけ、action.yml の書き方は check-jsonschema の --builtin-schema vendor.github-actions で検査できました。

check-jsonschema --builtin-schema vendor.github-actions .github/actions/*/action.yml
check-jsonschema --builtin-schema vendor.github-workflows .github/workflows/*.yml

再利用可能ワークフローと composite action の比較表

GitHub Docs の比較をもとに、書き方の違いを足した表です。

迷ったら「ランナーやジョブを分けたいか」「secrets・environment をまとめて扱いたいか」で決めます。 どちらも当てはまらない数ステップの部品は composite action が軽く書けます。

actionlint で検出できた誤り・できなかった誤り

actionlint 1.7.12 で、わざと誤りを入れて検査した結果です。

検出されなかったものも記録しておきます。GitHub 上で実行すると失敗するか、意図と違う動きになるものです。

$/ と cache-mode は GitHub Docs に載っている新しい書き方ですが、actionlint 1.7.12 ではエラーになります。 使う場合は、actionlint の -ignore で該当のメッセージを除くか、従来の ./.github/workflows/... で書きます。

actionlint -ignore 'unexpected key "cache-mode"'

よくあるエラーと直し方

public のリポジトリからは public の再利用可能ワークフローしか呼べません。 private のリポジトリからは private と public の両方を呼べます。GitHub がホストするランナーの割り当てと課金は、呼び出し元のリポジトリで決まります。

よくある質問

Q. 呼び出した側のファイルを更新したのに、再実行で前の版が動きます。 A. GitHub Docs によると、「失敗したジョブを再実行」は最初の実行と同じコミット SHA の再利用可能ワークフローを使います。「すべてのジョブを再実行」は uses の ref が指す最新の版を使います。

Q. 別リポジトリのワークフローは、タグとコミット SHA のどちらで指定しますか？ A. GitHub Docs は、安定性と安全性の理由からコミット SHA を勧めています。タグは後から付け替えられるためです。SHA で固定したときの更新の自動化は、関連記事「Dependabot・Renovate設定｜目的別コピペ設定集と比較表」で扱っています。

Q. 呼び出される側で github コンテキストは何を指しますか？ A. GitHub Docs では、呼び出される側の github コンテキストは呼び出し元のワークフローのものになります（github.workflow が呼び出し元の名前になるのもこのためです）。

GitHub Actions の基本は関連記事「CI/CDとは｜GitHub Actionsで最初のパイプラインを作るまで」、キャッシュと matrix は「GitHub Actionsのキャッシュとmatrix｜コピペ用YAMLとキー設計」で扱っています。

まとめ

• ジョブごと使い回すなら再利用可能ワークフロー（on: workflow_call → jobs.<id>.uses）、ステップをまとめるなら composite action
• inputs は string・number・boolean。outputs はジョブの outputs を経由して返す
• secrets: inherit は同じ組織・Enterprise の中だけ。secrets は直接呼んだ先にしか渡らない
• env は引き継がれない。with か vars
• 入れ子は10段・50種類まで（2025年11月に4段・20から引き上げ）
• 権限は呼び出し元で与え、呼び出される側は狭めるだけ
• actionlint は inputs・secrets・outputs の誤りを見つけるが、権限の広げすぎ・サブフォルダ・action.yml の中身は見ない。$/ と cache-mode は誤って指摘される

参考・出典

確認日はいずれも 2026年10月13日です。

• GitHub Docs「Reuse workflows」：https://docs.github.com/en/actions/how-tos/reuse-automations/reuse-workflows
• GitHub Docs「Reusable workflows reference」：https://docs.github.com/en/actions/reference/workflows-and-actions/reusing-workflow-configurations
• GitHub Docs「Reusing workflow configurations」：https://docs.github.com/en/actions/concepts/workflows-and-actions/reusing-workflow-configurations
• GitHub Docs「Metadata syntax reference」：https://docs.github.com/en/actions/reference/workflows-and-actions/metadata-syntax
• GitHub Docs「Contexts reference」：https://docs.github.com/en/actions/reference/workflows-and-actions/contexts
• GitHub Changelog「New releases for GitHub Actions – November 2025」：https://github.blog/changelog/2025-11-06-new-releases-for-github-actions-november-2025
• rhysd/actionlint v1.7.12：https://github.com/rhysd/actionlint
• check-jsonschema：https://github.com/python-jsonschema/check-jsonschema
• Eclipse platform-dev メーリングリスト（権限エラーの文面）：https://www.eclipse.org/lists/platform-dev/msg03876.html

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。