Composite actions: bundling steps with zero runtime overhead

What a composite action actually is

Why bother with a composite at all — why not just a reusable workflow or a script? Because a composite is the only type that adds zero runtime cost: when you see eleven copy-pasted steps becoming a maintenance burden, a composite collapses them into one uses: line without spawning a container or a Node process. Here is exactly how that works.

A composite action is metadata, not a program. Its action.yml declares runs.using: "composite" and a list of steps, and at call time GitHub Actions splices those steps into the calling job as if you had written them inline — they execute on the same runner, in the same workspace, under the same $GITHUB_WORKSPACE. There is no Node.js process to boot and no container image to pull, so the overhead of being an action is essentially a YAML parse: single-digit milliseconds against a job that already costs seconds.

# .github/actions/setup-toolchain/action.yml
name: "Setup Toolchain"
description: "Install the toolchain, restore cache, authenticate"
inputs:
  version:
    description: "Toolchain version"
    required: false
    default: "20"
outputs:
  cache-hit:
    description: "Whether the dependency cache was restored"
    value: ${{ steps.cache.outputs.cache-hit }}
runs:
  using: "composite"
  steps:
    - uses: actions/setup-node@v4
      with:
        node-version: ${{ inputs.version }}
    - id: cache
      uses: actions/cache@v4
      with:
        path: node_modules
        key: deps-${{ hashFiles('package-lock.json') }}
    - name: Install
      shell: bash
      run: npm ci

Two rules bite senior authors here. First, every run: step inside a composite must declare shell: — there is no job-level default to inherit, so a bare run: block fails validation. Second, inputs are not environment variables: inside the composite you read them as ${{ inputs.version }}, not $VERSION, and to surface a value to the caller you wire it through outputs[].value referencing a step’s output, as the cache-hit plumbing above shows.

The tradeoff: speed bought with shared state

The thing a composite gives you for free is also the thing that can hurt: no isolation. It runs in the caller’s environment, sees the caller’s files, and mutates the caller’s filesystem. If your composite runs npm install -g some-cli, that binary is now on PATH for every later step in the job — convenient until two composites install conflicting global versions. There is no node_modules sandbox, no dependency vendoring; a composite that depends on jq assumes jq is already on the runner. This is fine for orchestration — sequencing tools the runner already has — and wrong for logic that needs its own pinned dependencies. That latter case is exactly what JavaScript and Docker actions exist for.

When you install a global CLI in a composite, ask yourself: will the next composite in this job expect a clean PATH, or is it fine if your binary is already there? That question surfaces the real danger before it bites you in production.

Two further sharp edges. Composites can nest and call other actions, but error handling is coarse: a failed step aborts the composite the way a failed job step aborts a job, and pre-1.0 you could not even use continue-on-error per step (now supported, but if: conditions on composite steps still evaluate differently from workflow steps — they do not see job-level success()/failure() state the same way). And security pinning applies recursively: when your composite does uses: actions/cache@v4, that tag is mutable. For anything touching credentials, pin nested actions by full commit SHA — uses: actions/cache@<40-char-sha> — so a compromised tag in a dependency cannot inject code into every workflow that calls your composite.