Reusable Workflows vs Composite Actions in GitHub Actions

Choose between a reusable workflow and a composite action in GitHub Actions: call level, jobs, runners, logging, secrets, limits, and working examples of each.

Published

At a glance

Last reviewed
Versions referenced
actions/checkout@v7 actions/setup-node@v7 org/repo/.github/workflows/lint-test.yml@v1
Reading time
4 min read

Code samples are not run in a live repository. See our editorial standards.

On this page

Use a reusable workflow when you need to share whole jobs, including their runners. Use a composite action when you need to share a sequence of steps that run inside a job you already control. A reusable workflow is called at the job level (jobs.<job_id>.uses); a composite action is called as a step (steps[*].uses).

Comparison

Feature Reusable workflow Composite action
Definition A single YAML file in .github/workflows/ of a repository A repository or directory containing an action.yml file and, optionally, other files
Called by Referencing a specific YAML file Referencing a repository or directory
Call level Directly in a job (jobs.<job_id>.uses), not from a step As a step within a job
Jobs Can contain multiple jobs Cannot contain jobs
Runners Each job sets its own runs-on Runs on the caller job’s runner
Logging Every job and step is logged separately, in real time Logged as one step in the caller, even if it contains many steps
Secrets Can use secrets Cannot use secrets directly; pass values as inputs
Nesting Up to ten levels of workflows Up to 10 composite actions nested in one workflow
Marketplace Cannot be published Can be published

Choose by what you need to share

Pick a reusable workflow in these cases:

  • The shared logic needs more than one job, or a different machine type than the caller job.
  • You want each job and step logged separately.
  • The work needs secrets, passed with secrets: or secrets: inherit.

Pick a composite action in these cases:

  • You want to bundle steps and run them in the middle of an existing job, with other steps before and after.
  • You want to publish the action to the Marketplace.

Output handling differs too. You can’t add steps to a job after calling a reusable workflow. Its outputs are available to later jobs through needs. A composite action is a step, so later steps in the same job can use its outputs directly. For a related walkthrough, see Pass Outputs Between GitHub Actions Jobs.

Same lint-and-test logic, both ways

Reusable workflow

The reusable workflow is triggered by workflow_call and brings its own runs-on. Create .github/workflows/lint-test-reusable.yml:

name: Reusable Lint and Test

on:
  workflow_call:
    inputs:
      node-version:
        required: true
        type: string

jobs:
  lint-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

      - uses: actions/setup-node@v7
        with:
          node-version: ${{ inputs.node-version }}

      - name: Install dependencies
        run: npm ci

      - name: Run linter
        run: npm run lint

      - name: Run test suite
        run: npm test

Call it from .github/workflows/ci.yml. The uses key sits on the job, and the caller job has no runs-on or steps:

name: CI

on:
  push:
    branches: [main]

jobs:
  call-lint-and-test:
    uses: ./.github/workflows/lint-test-reusable.yml
    with:
      node-version: '20'

For a workflow in another repository, use owner/repo/.github/workflows/lint-test-reusable.yml@v1, where the ref after @ is a tag, branch or commit SHA.

Composite action

A composite action has no runner and no jobs. Every run step needs an explicit shell. Create .github/actions/lint-test/action.yml:

name: Composite Lint and Test
description: Installs dependencies, lints, and runs tests

inputs:
  node-version:
    description: Node.js version to set up
    required: true

runs:
  using: composite
  steps:
    - uses: actions/setup-node@v7
      with:
        node-version: ${{ inputs.node-version }}

    - name: Install dependencies
      shell: bash
      run: npm ci

    - name: Run linter
      shell: bash
      run: npm run lint

    - name: Run test suite
      shell: bash
      run: npm test

Call it as a step in a job you define:

name: CI

on:
  push:
    branches: [main]

jobs:
  lint-and-test-job:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

      - name: Run lint and test action
        uses: ./.github/actions/lint-test
        with:
          node-version: '20'

The caller must run actions/checkout first. A local path like ./.github/actions/lint-test is resolved from the checked-out workspace, so without checkout the runner can’t find action.yml.

Common pitfalls

Calling a reusable workflow from a step

A reusable workflow can’t be referenced under steps. Workflow validation rejects it, and the step-level uses is reserved for actions. Move the uses to the job:

# Wrong: a reusable workflow referenced from a step
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: org/repo/.github/workflows/lint-test.yml@v1
# Right: the reusable workflow is the job
jobs:
  test:
    uses: org/repo/.github/workflows/lint-test.yml@v1
    with:
      node-version: '20'

If you need the shared logic to run as a step, convert it to a composite action.

Missing shell in a composite action

Each run step in a composite action must declare shell. Omitting it makes the action metadata invalid, so add shell: bash (or another shell) to every run step.

Checkout in a reusable workflow checks out the caller

When a reusable workflow from another repository uses actions/checkout, it checks out the repository that hosts the caller workflow, not the repository that hosts the reusable workflow. Check out the called repository explicitly if you need its files.

Private and internal repositories

For internal or private repositories, the Access policy on the Actions settings page of the called workflow’s repository must allow access from the repositories that contain the callers. Without that, the call fails.

Renamed repositories

GitHub Actions doesn’t follow redirects for actions or reusable workflows. If the owner or repository name changes, workflows that use the old name fail until you update the reference. For a related walkthrough, see Run GitHub Actions Jobs Only When Specific Files Change.

Passing secrets to a composite action

A composite action has no secrets key. Declare an input and pass the secret from the caller:

- uses: ./.github/actions/lint-test
  with:
    node-version: '20'
    registry-token: ${{ secrets.REGISTRY_TOKEN }}

Add registry-token to the action’s inputs as well.

Verify the setup

  1. Push the caller workflow and open the run in the Actions tab.
  2. For a reusable workflow, confirm the run graph shows the caller job (call-lint-and-test) with the called job nested under it, and that each step is listed separately.
  3. For a composite action, confirm the caller job shows one step, Run lint and test action, and expand it to see the inner steps’ output in that single log.
  4. If a reusable workflow defines outputs under on.workflow_call.outputs, read them in a later job with ${{ needs.<job_id>.outputs.<output_name> }} and print them with echo to confirm the values.
  5. If the workflow doesn’t start at all, check the Actions tab for a validation error on the workflow file. The usual causes are uses under steps for a reusable workflow or a missing shell in a composite action.

Spotted an error? Report it on our Contact page and see our editorial standards for how we correct articles.