GitHub Actions YAML Anchors/Aliases Not Working in Workflows

A workflow using YAML anchors and aliases (&name, *name, the << merge key) to deduplicate steps does not behave as expected, because GitHub Actions does not support anchor/alias reuse the way plain YAML does.

What this error means

A workflow relying on YAML anchors/aliases to share step blocks is rejected or ignores the reuse, because the Actions parser does not expand anchors for workflow reuse.

# anchors like this are NOT reliably supported for reuse in Actions
defaults: &common
  run:
    shell: bash
jobs:
  a:
    <<: *common   # not the supported reuse mechanism

Common causes

Actions does not use anchors for reuse

GitHub Actions provides its own reuse primitives and does not support YAML anchors/aliases/merge keys as a way to deduplicate jobs or steps.

Expecting plain-YAML behavior

Anchors work in generic YAML tooling, so it is natural to assume Actions honors them - but the workflow schema is the contract, not raw YAML merge semantics.

How to fix it

Use the supported reuse primitives

Factor shared steps into a composite action or a reusable workflow, and use a matrix to fan out variants.

# reusable workflow for shared jobs
jobs:
  ci:
    uses: ./.github/workflows/shared-ci.yml
# or a composite action for shared steps
- uses: ./.github/actions/setup

Pick the right tool for the duplication

1. Composite action: reuse a sequence of steps inside jobs.
2. Reusable workflow: reuse whole jobs across workflows.
3. Matrix: run the same job over multiple parameter combinations.

How to prevent it

• Do not rely on YAML anchors/aliases for workflow reuse.
• Use composite actions, reusable workflows, and matrices instead.
• Treat the Actions schema as the source of truth, not raw YAML semantics.

Related guides