GitHub Actions "reusable workflows can not be nested more than 4 levels" in CI

By Daniel Zoghalchali·Latchkey

A caller plus its chain of called workflows can go at most four levels deep. When a reusable workflow calls a reusable workflow that calls another, and so on past the limit, GitHub rejects the run.

What this error means

The run fails with "reusable workflows can not be nested more than 4 levels deep" (or "more than N levels"). The deepest call in the chain is refused.

error parsing called workflow
".github/workflows/a.yml" -> "b.yml" -> "c.yml" -> "d.yml" -> "e.yml":
reusable workflows can not be nested more than 4 levels deep.

Common causes

A call chain deeper than the limit

Each workflow_call adds a level. Five workflows calling each other in a line exceed the four-level maximum.

A shared workflow that itself calls others

A widely reused workflow that internally calls more reusable workflows can push callers over the limit unexpectedly.

How to fix it

Flatten the call chain

1. Map the current nesting from the error trace.
2. Collapse intermediate wrapper workflows so the chain fits within four levels.
3. Inline a level as jobs where a wrapper adds no value.

jobs:
  build:
    uses: ./.github/workflows/build.yml
  deploy:
    needs: build
    uses: ./.github/workflows/deploy.yml

Replace a nesting level with a composite action

A composite action bundles steps without adding a workflow_call level, so moving shared steps there can shorten the chain.

# a job step instead of another nested workflow
- uses: octo-org/shared-steps@v1

How to prevent it

• Keep reusable-workflow chains shallow, ideally two levels.
• Prefer composite actions for shared steps, which do not add nesting.
• Document how deep a shared workflow already nests before reusing it.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions