Composite Actions

~12 min · composite, action, reusable

Level 0Apprentice

0 XP0/101 lessons0/10 achievements

0/120 XP to next level120 XP to go0% complete

Reusable steps inside a job

A composite action is a YAML file that bundles multiple steps into a single uses:-able unit. Where a reusable workflow is a whole job running on its own runner, a composite action is just a sequence of steps that runs inline in the calling job's runner.

When to pick which

Reusable workflow — when you want a whole job (separate runner, parallel, with its own permissions). Best for 'run our standard test suite' or 'do our standard deploy'.
Composite action — when you want a repeatable sequence of steps within an existing job. Best for 'set up our weird Python env' or 'build and tag our Docker image'.

Anatomy

A composite action lives at .github/actions/<name>/action.yml (local) or in its own repo (shared). The file declares runs.using: composite and a list of steps.

Code

Composite action — local·yaml

# .github/actions/setup-pippa-env/action.yml
name: 'Setup Pippa env'
description: 'Install Python 3.12 + uv + project deps'
inputs:
  python-version:
    description: 'Python version'
    required: false
    default: '3.12'
outputs:
  cache-hit:
    description: 'Whether deps were restored from cache'
    value: ${{ steps.uv.outputs.cache-hit }}
runs:
  using: composite
  steps:
    - uses: astral-sh/setup-uv@v3
      id: uv
      with:
        version: '0.5.x'
        enable-cache: true
    - run: uv python install ${{ inputs.python-version }}
      shell: bash
    - run: uv sync --all-extras --dev
      shell: bash

Caller — uses the composite·yaml

      - uses: ./.github/actions/setup-pippa-env
        with: { python-version: '3.12' }
      - run: pytest -q

External links

GitHub — Creating composite actions

Exercise

Find a 5+ step sequence that's repeated across two jobs in your workflow. Extract it to a composite action under .github/actions/. Both jobs become one uses: + the steps that actually differ.