Feature request: allow workflow configuration in sub-folders

[solarmosaic-kflorence]

Copying this feature request over from https://github.community/t/feature-request-allow-workflow-configuration-in-sub-folders/16776

We use a monorepo setup and currently everything is organized into sub-folders, so for example all services are located in the “services” folder. Currently workflow configuration is the only code which relates to a service that is not in the applicable “services” folder (e.g. “services/foo-service”). In order to maintain clean code separation and ownership, it would be nice if we could place our workflow configuration for a specific service in it’s appropriate folder. The most straightforward solution would seem to be matching on any .github folder in the repo, not just the root one. This would allow us to place workflows in the “services/foo-service/.github/workflows” folder, for example.

[MunchyYDL]

I was searching for a way to organise many workflows in the UI, like by category or by team for a mono-repo. And I was thinking about just being able to create subfolders in the ./github/workflow/ folder, and that each folder would appear as a collapsable section in the UI.

But this proposal would be even better, at least when it comes to separation of files, but I'm not sure how it would be presented in the UI?

[amitfmg]

I like the suggestion about collapsible folders on the UI.

[chaddyc]

@MunchyYDL, keen to see if Github will implement/develop this feature.

[garrmark]

I'd like to add my support for the folders under .githuib/workflow that would be displayed as collapsable folders in the UI

[eliezercazares]

This is enough for my needs. I have setup Automated Tests in the Workflows, using the Runners. And it's so many suites and tests that being able to organize my test suites would be cool. Because I also have workflows that do Slack notifications and are reused. So a common/ folder would be good for those.

[dselvi]

This would be really useful.
Otherwise, we have a huge jungle full of workflows running for different environments/ChangeMgmt Levels, it becomes kind of an aesthetic mess.

[zachsa]

I was trying to do:

.github/
  - workflows/
    - dir_1
      - a.yml
      - b.yml
      - etc
    - dir_2
      - a.yml
      - b.yml
      - etc

With the hope that I would see a list of actions as

dir_1_a
dir_1_b
dir_1_c
dir_2_a
dir_2_b
dir_2_c

or something similar. Since the action names are configured in the yml files it would make sense to namespace actions according to the directory they are in. For my use case, aside from namespacing actions via a directory name, nothing would change (though since I use only a small subset of actions functionality I'm not sure if there are other considerations).

It would be nice if it was possible to put .github folders anywhere.

In any case, thank you for the actions tooling! It's pretty amazing.

[krtschmr]

seems quite tricky to scan all folders for a .github folder. subfolders in the .github would be sufficient i believe

[san7890]

It would also be rather nice if there could be a way to run a workflow nested in a submodule, and then leverage that same submoduled workflow to work on the parent repository. This is definitely a much bigger ask than what the original discussion was most likely tailored for, but it would certainly come in use for a repository I currently maintain.

[alfreddagenais]

This will help a lot my team for a mono-repo! I hope to saw this feature soon

[jsoref]

You can do a lot of this by using a services/foo-service/action.yml and then put uses: ./services/foo-service/ into your .github/workflows/foo-service.yml.

It isn't perfect, but, you can do it.

Or, you could just use CODEOWNERS and have that map ownership of .github/workflows/foo-service-* to @foo-service.

Forcing GitHub to recurse through the entire tree, or even a large slice of a tree whenever it receives any event is almost certainly a non-starter. I appreciate the problem, but don't think that asking them to do this is likely to go anywhere.

What you can do is have your workflow load its configuration from a file at a path in your chosen directory. Many public workflows do this, although typically that directory is .github/actions/{action-short-name}/

[tn3rb]

Forcing GitHub to recurse through the entire tree, or even a large slice of a tree whenever it receives any event is almost certainly a non-starter.

what do you think is going to happen if you have a bunch of files like

.github/workflows/foo-service.yml
.github/workflows/bar-service.yml
.github/workflows/baz-service.yml

that all implement use to point to additional actions in subfolders like:

# in .github/workflows/foo-service.yml
uses: ./services/foo-service/ 

# in .github/workflows/bar-service.yml
uses: ./services/bar-service/ 

# in .github/workflows/baz-service.yml
uses: ./services/baz-service/ 

GitHub is going to load all of those actions in the root of .github/workflows and THEN have to ALSO go into those subfolders anyways.

Sound like even more work than just recursing through a folder structure like:

.github
    - workflows
        - foo
            - service.yml
        - bar
            - service.yml
        - baz
            - service.yml

which is not an unreasonable request in this day and age

[jsoref]

That isn't how the GitHub Action Runtime works.

When it gets an event, it only needs to enumerate objects in a single folder (on at most two branches -- default and the current one).

For each object, it then decides if the workflow is enabled, and then if the workflow applies.

If it's enabled and it applies, then it dispatches it to a mechanism that will send things to runners which will then digest the uses lines. It's done much later in the pipeline, and it isn't done by enumerating all objects in the repository, it looks for very specific paths ./services/baz-service/ {action.yaml | action.yml }

[jeffrey-aguilera]

find .github/ -type file -name *.yml is incredibly fast. There is really no excuse for preventing users from organizing their workflows.

[sparr]

@jeffrey-aguilera Not only do some repos contain yaml files that aren't github workflows, some repos contain valid github workflows as the content of the repo, not as workflows to be run on that repo.

[Anonymous-Coward]

You can do a lot of this by using a services/foo-service/action.yml and then put uses: ./services/foo-service/ into your .github/workflows/foo-service.yml.

My biggest gripe with this is that it doesn't give you any possibility to organize workflows in the UI. I have several dozen workflows, over a hundred, which do exclusively the uses thing with a handful of reusable workflows. It's time-consuming, with the current actions UI, to find the one I'm looking for. Without some structure inside /github/workflows, or an artifficially created one by specifying something like `path: ["sub-dir-1", "sub-dir-2", "sub-dir-3"] for the workflows to be shown in a tree structure, I can't see how reusable actions/workflows can help with this problem.

[sam0x17]

A good workaround is symbolic links in your root directory .github/workflows folder

[raihle]

I'm not sure that works at all, but I know it doesn't work when adding, removing, or renaming workflow files

[socketbox]

This does not work

[sam0x17]

yes it does not work unfortunately. Wish it did

[danielfigueiredo]

I've tried using symbolic links and GHA will raise errors when trying to parse workflow files

[Anonymous-Coward]

A good workaround is symbolic links in your root directory .github/workflows folder

Not really. Even if it would work, the workflow links inside .github/workflows would still be presented as soup. You can't easily work with that soup when you have well over a hundred workflows in the same repo.

[zomgbre]

This feature would be awesome to have for when using both re-usable workflows and the "regular" workflow. Right now, I'm naming things with emojis in front of them to do this. 😂 It gets a little ⚡ if it's a re-usable.

[zomgbre]

All I did was paste in the emoji in vscode in front of the name :P it was a little silly:

name: '⚡ ci'
on:
  workflow_call:
    inputs:
      node-version:
        description: Node version
        type: string
        required: true
      working-directory:
        description: Working directory to use
        type: string
        default: './'

jobs:
  test:
    name: Test
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: ${{ inputs.working-directory }}
    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Use nodejs ${{ inputs.node-version }}
        uses: actions/setup-node@v3
        with:
          node-version: ${{ inputs.node-version }}
          registry-url: 'https://npm.pkg.github.com'

      - name: Install with package-lock
        run: npm ci
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}

      - name: Compile typescript
        run: npm run build
      - name: Tests
        run: npm run test

I have since abstracted these workflows into a separate repository and now referencing them like so across several similar projects:

name: ci
on:
  pull_request:
    branches:
      - main
      - release/**

permissions:
  contents: read

jobs:
  ci:
    uses: orgname/repo-name/.github/workflows/ci.yml@main
    secrets: inherit
    with:
      node-version: 18

[granthorner]

thanks @zomgbre I guessing there's no way to actually display the emoji directly within the github actions list in a way to help group them?

[jsoref]

You can certainly use emoji in the name: field w/in workflows...
https://github.com/jsoref/sample-nested-workflows/actions

[zomgbre]

You can copy the emojis from here: ❤️
https://gist.github.com/rxaviers/7360908

It's gotta be the actual emoji and not the markdown :heart: Hehe, it seems counter-intuitive a bit because you'd think it would render with the colons.

[granthorner]

Ah that's amazing, that's where I was going wrong....much appreciated for your help @zomgbre

[sam0x17]

Apparently it doesn’t work

…

On Tue, Aug 2, 2022 at 6:32 AM Tim Kretschmer ***@***.***> wrote: How can i achieve this? ln -s ? — Reply to this email directly, view it on GitHub <#18055 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAOE4LLF6VBUR4F74GVLKSLVXD2KHANCNFSM5YELZWBA> . You are receiving this because you commented.Message ID: ***@***.***>

[ErikBjare]

You mean the symlink suggestion?

[rodrigo-georgian]

Instead of recursing through the whole repo, why not provide a keyword in the root .github/workflows that can be used to point to the "sub-root" of the directory you want to treat as it's own repo (for actions)?

Something like this:

In /.github/workflows/package_1.yaml:

redirects: './package_1'

In /package_1/.github/workflows/package_1.yaml:

# regular github actions config, as if this were the root package

Benefits:

• Almost complete code separability. (Only needs to add that one line / file to the root)
• No need to recurse anything.

[rawnly]

Couldn't this can be archived via the uses keyword as mentioned before?

[Updatephoneme]

Copying this feature request over from https://github.community/t/feature-request-allow-workflow-configuration-in-sub-folders/16776

We use a monorepo setup and currently everything is organized into sub-folders, so for example all services are located in the “services” folder. Currently workflow configuration is the only code which relates to a service that is not in the applicable “services” folder (e.g. “services/foo-service”). In order to maintain clean code separation and ownership, it would be nice if we could place our workflow configuration for a specific service in it’s appropriate folder. The most straightforward solution would seem to be matching on any .github folder in the repo, not just the root one. This would allow us to place workflows in the “services/foo-service/.github/workflows” folder, for example.

[kr99]

This would be a nice feature for our template projects, to make certain workflows optional and easy to tear out (with related scripts). eg. "Not using the event queue system? tear out the workflow and related integration testing scripts by pulling ONE folder..."

Suggested workaround: strictly enforced naming conventions on the workflow files. e.g. "event_queue.integration_test.stage.yml" mirroring a folder src/event_queue or something (I don't like my example a ton, but it illustrates the point)

[tn3rb]

also running a monorepo and having workflow subfolders would be great as we have a lot of granular separation going on.

this would be ideal for us:

.github
    - workflows
        - foo
            - deploy.yml
            - e2e-test.yml
            - unit-test.yml
        - bar
            - deploy.yml
            - e2e-test.yml
            - unit-test.yml
        - baz
            - deploy.yml
            - e2e-test.yml
            - unit-test.yml

[rawnly]

I've been following this thread for a while, if you're interest I made a simple cli in rust that can help with workflows context separation. Is still a WIP, nothing fancy. Hope this helps someone ✌️

https://github.com/rawnly/hawk

[rodrigo-georgian]

Pragmatic solution, thanks @rawnly

[rawnly]

If anyone willing to use it, I just updated and released hawk, now is "generally available" ✌️

[dsdavis4]

Has there been any progress made on this? Being able to define a .github directory within subfolders would be ideal, however what @tn3rb suggested would also be great.

[adikari]

We are using monorepo setup and our .github/worflows is getting out of control. Before Actions, we were using Buildkite and it allowed to add workflows in specific folders for services as suggested by the OP. The root workflow is getting too big and unmanageable and we are considering moving back to Buildkite just for this reason :(

[SvetaSR]

Pleaseee Github do somethinggg with it

[dselvi]

Hello, Jenkins,
Yeah, this is Github. I need your help.
Please send me the magical way you nest Pipelines in Sub-Folders.
Our guys are stumped. I asked everyone and they're like "Huh? No Way!"
Thanks--
Oh, and I take back everything I said about you when we went live :-)

[roperi]

+1

[madsem]

Oh god, I spend hours organizing everything into folders for our monorepo that spans several business units, only to get:

Invalid workflow file: .github/workflows/production.yml#L39
invalid value workflow reference: workflows must be defined at the top level of the .github/workflows/ directory

Really surprised this isn't possible, having several dozen workflows in the top level dir all for different business units, is super annoying

[DoLoop216]

Welcome to the club

[dselvi]

Uh, yeah. I wouldn't say not having sub-folders is "archaic". However, it does feel a bit like going back to the 2000-2010 era again when everyone was writing in python. What's the deal?

[AFMiziara]

I don't know why GH bothers to have a discussion section to hear its user's opnions if they clearly just don't care about it.

[thardy]

+1

This is a very easy thing to implement, and it was suggested and supported by many, many developers. I got here from this suggestion (yet another) - https://github.com/orgs/community/discussions/11831.

It would be very easy to implement folders or tags on workflows and the ability to view by folders or tags - maybe even go crazy and let people collapse them.

The fact nothing at all has been done makes you wonder what's going on over in github development land.

[carlo-setldpay]

Having sub folder supports would be really helpful in managing 20+ workflows in a mono-repo as it keeps increasingly difficult to manage it. I'm surprised even after 3 years there's been no update on this.

[yardenoff]

It’s June 2025 and we’re still organizing dozens of files by naming convention like we’re living in a man cave with no shelves. Just vibes and chaos.

[MrAtkinson]

@andrewakim @nebuk89 @lkfortuna Hello! Checking in for updates on this [highly requested] ticket.

[DoLoop216]

At this point I am convinced they keep this as their morning fun. While sipping hot nice coffee, they scroll and laugh at new people having encountering this problem.

They are like "Huh, you thought it was obvious, but we got you!", sip, sip, sip... hahaha, sip...

[ivanOstymchuk]

In Azure DevOps Pipelines this feature has been available for years. Since Github is Microsoft, why it is not implemented yet?

[Gabsop]

+1!

[patric-dosch-vi]

my first mono repo and it's sadly a Github mess :(

[lgoria]

First time working mono repo. I was happy, organized all my workflows in folders... Took me years to rename everything. All for nothing :,(|

[AlexanderWangY]

I also just did this in a monorepo... could not overstate my disappointment.

[DoLoop216]

That means you will experience happiness 2 times. First is when you were organizing your workflow files. Second will be in abt 7 years when they finally implement this.

[shanti-razr]

this is lame let us use file directories!