Reusable Workflow Depth Limit

[automartin5000]

The depth limit of 2 is too low. For my use case, I'd need at least 3:

1. Orchestrator workflow
2. High level "steps" (think: environment deployments)
3. Reusable workflows within those steps

[chrispat]

Depending on what level of reused you need you could consider composite actions as well.

[automartin5000]

Depending on what level of reused you need you could consider composite actions as well.

So what's the difference between a composite action and a reusable workflow?

[umarcor]

See pyTooling/Actions: Context:

• Composite Actions can be executed from a remote/external path or from the checked out branch, and from any location. However, Reusable Workflows can only be used through a remote/external path ({owner}/{repo}/{path}/{filename}@{ref}), where {path} must be .github/workflows, and @{ref} is required.
  See actions/runner#1493.
  As a result:
  • Local Composite Actions cannot be used without a prior repo checkout, but Reusable Workflows can be used without checkout.
  • Testing development versions of local Reusable Workflows is cumbersome, because PRs do not pick the modifications by default.
• Composite Actions can include multiple steps, but not multiple jobs.
  Conversely, Reusable Workflows can include multiple jobs, and multiple steps in each job.
• Composite Actions can include multiple files, so it's possible to use files from the Action or from the user's repository.
  Conversely, Reusable Workflows are a single YAML file, with no additional files retrieved by default.

See also pyTooling/Actions: Callable vs dispatchable workflows.

[nfourtythree]

Would love to see this limit increased. Even to 3 would make the possibility for configuration greatly improved.

The ability to create configurable reusable actions would improve DRYness across repositories.

[param-finder]

Github actions is just so disappointing when it comes to re-usability. Look at CircleCI, Github should take notes.

[wdcbigblue]

I have to say, this difference between Reusable Workflows and Composites along with the strict 2-level depth limit on reusable workflows adds needless complexity to some pretty basic CI tasks. https://github.blog/2022-02-10-using-reusable-workflows-github-actions/ shows the difference between the two. I fully recognise there should be some depth limit to reusable workflows, but if the limit is 2 then I'd have to question the true use case of this functionality.

@automartin5000 simple example is probably a good indication of the "base case" for this functionality.

[wdcbigblue]

I have returned and solved my problem by curing myself of my ignorance. For anyone else happening upon this: Seems like a more elegant way to do this is with composite local actions. You have to structure these with a directory under your .github dir like .github/actions/action.yaml as the root file. Reference this from a job via the usual way i.e

uses: ./.github/actions/path_to_action

and it will use the action.yaml file for you automatically.

[JordanShurmer]

Just to clarify for those reading this: add that uses reference to a step within a job, not to the job as if it were a re-usable workflow.

see more: https://docs.github.com/en/actions/creating-actions/creating-a-composite-action

[OliverRC]

I'd also like to see nested reusable workflows as an option. The alternative of composable actions is wholly inadequate for being able to have DRY and composable YAML workflows (no secrets, seen as a single step, only a single job).

The depth limitation forces copy-pasted workflows that are identical but necessary because they cannot be nested.
e.g consider the following structure

Continous Delivery.yml
└ Build and Deploy.yml
  └ Deploy.yml

Release 
└ Deploy.yml

This is impossible right now. One has to block copy the Deploy.yml into Build and Deploy.yml to make things work.

[mvs5465]

Is this depth limit configurable in GHE, or is the 2 hardcoded?

[e3b0c442]

Please address this limitation. Composite actions are not a good alternative for many of the use cases outlined here.

[jharris-tc]

Just want to add to the consensus here, this would be incredibly useful

[chrispat]

You can now nest up to 4 levels of reusable workflows
https://github.blog/changelog/2022-08-22-github-actions-improvements-to-reusable-workflows/

[OliverRC]

That's fantastic! Well done team

[JoshMcCullough]

Is the error message incorrect (should it say "4" instead of "3")? This is using GH public, not on-prem:

...but doing so would exceed the limit on called workflow depth of 3

[mikejflex]

This link is broken atm.

[ChristopherHX]

This link is broken atm

Yes it is, found that url by using search.
https://github.blog/changelog/2022-08-22-github-actions-improvements-to-reusable-workflows-2/

Why does this link has a -2 suffix?

[kishaningithub]

Have it the 4 limit. Can this be increased to 8 or this limit itself be removed?

[d97kja]

Am trying to nest levels with reusable workflow but it fails? What am I doing wrong? Can GitHub action really handle nested workflows? Can someone pls clear this out.

File: A.yaml
name: A
on:
workflow_dispatch:
jobs:
job1:
uses: xxxx/xxxxxxxx/.github/workflows/B.yaml@main

File B.yaml:
name: B
on:
workflow_call:
jobs:
job2:
uses: xxx/xxxxxxxx/.github/workflows/C.yaml@main

File C.yaml
name: C
on:
workflow_call:
jobs:
job3:
name: job3
runs-on: xxxx
steps:
- run: echo "Hello world in job3 and level C"

Am getting:
Invalid workflow file:
error parsing called workflow
.....
but doing so would exceed the limit on called workflow depth of 1

[OliverRC]

Ah, I see it has changed since the discussion started. See the accepted answer by @chrispat

[d97kja]

Yes, but it doesnt work for me according to what is written in the documentation. How ever we do have an on-prem GitHub installation. Is there any functionality for GitHub actions that needs to be enabled? Running latest version.

[chrispat]

This feature has not shipped in GHES yet. When it does it will be part of the release notes but I think the version that it will be in is 3.7.

[d97kja]

Thanx chrispat for the information!

[lukestoward]

Hi @chrispat, do you know when this increase to workflow depth will make it to GHE? It doesn't appear to be part of 3.7.x thus far.

[JoshMcCullough]

3/4 levels is not enough, IMO. It's still very limiting. I've already run into this while writing my very first set of workflows!

[e3b0c442]

Would also like to request this be increased. It honestly seems that this is an unnecessary artificial limitation (or one borne of a suboptimal implementation). Our workflows is not terribly complex -- I'm just trying to reuse some logic between workflows in a monorepo -- but I've hit even the raised limit several times and had to introduce additional complexity to work around it.

Composite actions and reusable workflows target two completely different needs and composite actions are not a good substitute for reusable workflows.

[snps-midhunn]

The depth limit is a pain if you are promoting DRYness. The reusability is very much limited in GitHub Actions.
How can we tackle a scenario of this sort?
caller.yml -> ci-reuse.yml (Some reusable workflow org wide)
Inside ci-reuse.yml its using matrix strategy for another reusable workflow called platform.yml
and for each platform there is multiple flavors being built such Debug, Release, etc which is again a matrix calling flavors.yml

So the map becomes:

flowchart LR
    caller.yml --> ci-reuse.yml
    ci-reuse.yml --> platform.yml -.-> x64
    platform.yml -.-> x86
    platform.yml -.-> arm
    x64 --> flavor.yml 
    x86 --> flavor.yml 
    arm --> flavor.yml 
    flavor.yml -.-> x64-Release
    flavor.yml -.-> x64-Debug
    flavor.yml -.-> x86-Release
    flavor.yml -.-> x86-Debug
    flavor.yml -.-> arm-Release
    flavor.yml -.-> arm-Debug

Loading

[h2oearth]

Unfortunately, just like you guys, I am in the same boat :-(! GH, are there any plans to increase the minimum depth Limit to > 5?

[LuisOchoa-AA]

Same issue here. Need a limit increase please.

[nikhilbadyal]

Limit increase please. It's 3 not 4, in fact.

[dariocurr]

Please increase the limit

[pbrennand-francis]

I agree Github Actions would benefit by increasing the limit or providing clear guidance around how we're supposed to architect systems of reusable CI code without a higher workflow call depth than is currently offered.

[dezren39]

limit

[gabo-urrutia-inditex]

This limit is really painful as it leads to a lot of code repetition. :(

[bstriner]

Hoping for a limit increase, composite actions are not a workaround. Certain features like "matrix" are limited to workflows, so you can use nested actions but then you can't have loops. You can write a shell loop in an action but then are unable to write a loop that calls another action. Only workflow_dispatch and waiting on completion provides a workaround but a lot of extra scripting. Bumping it up to even 5-7 would provide a lot of flexibility and is far short of typical stack limits. Cheers!

[dezren39]

It's such an own goal, you're better off setting everything to dispatch and use gh cli in your jobs with a custom token.

[kishaningithub]

Can you give an example of this approach?

[kishaningithub]

Especially on orchestration

[dariocurr]

Still no news? This unnecessary limitation is very frustrating and against every DRY principle

[JoshV-Silvaco]

I could get by with three levels, but I need them to be grouped in the UI or the UI is useless for following along... it's just a big mess of all the different platforms, precisions, etc I'm building.

[nebuk89]

Hello :)
https://github.blog/changelog/2025-11-06-new-releases-for-github-actions-november-2025/

You can now use up to 10 nested reusable workflows and call up to 50 workflows in total from a given workflow run. The previous limits were four and 20, respectively.

[nebuk89]

I know folks may want more, but for now I am going to close this issue. Getting up from the 2 we started with to 10 feels pretty solid and I would just <3 a fresh issue with new votes to better judge if we need to go even higher.

Sorry this took a while for us to increase but we got there :D

[dimon222]

Only github.com or does it also come in self-hosted github enterprise?

[kishaningithub]

Now the only crib i have is that they improve the UX of a deeply nested pipeline. As of now they just flatten it out and this drops all the associated "hierarchical context" to the user of the pipeline.