Composite Actions

action.yml with runs.using: composite

A composite action packages several steps into one reusable step, defined in an action.yml with inputs, outputs and runs: using: composite. Use it for repeated step sequences (set up toolchain, restore cache, install), while reusable workflows suit whole jobs. Composite actions can live in the same repository (uses: ./.github/actions/setup) or their own repository. JavaScript and Docker actions are alternatives when you need more logic.

A local composite action

Not linted or run here; check the GitHub Actions documentation for current syntax.

# .github/actions/setup/action.yml
name: Setup project
inputs:
  node-version:
    default: "22"
runs:
  using: composite
  steps:
    - uses: actions/setup-node@v4
      with: { node-version: "${{ inputs.node-version }}", cache: npm }
    - run: npm ci
      shell: bash        # composite run steps must declare a shell

# usage in a workflow, after actions/checkout:
#   - uses: ./.github/actions/setup

Declare shell in composite run steps

Composite run steps require an explicit shell, a frequent first-time error.

Quick check: When is a composite action a better fit than a reusable workflow?

• When reusing whole multi-job pipelines
• When reusing a sequence of steps inside jobs
• When you need a cron schedule
• Never