Allow reusable workflows to be located at arbitrary locations and be local

Describe the enhancement

Although the documentation does not specify the limitation, it seems that reusable workflows must be located in .github/workflows. Moreover, specifying the version is necessary. Therefore, it is not possible to have a reusable workflow in the current branch.

It would be desirable if the syntax was changed to [{owner}/{repo}/]{path}/{filename}.yml[@{ref}].

You reference reusable workflow files using the syntax:



invalid value workflow reference: references to workflows must be rooted in ‘.github/workflows’


invalid value workflow reference: no version specified

Ref: Allow reusable workflows to be located at arbitrary locations and be local · Issue #1493 · actions/runner · GitHub


In fact you can have a reusable workflow in the current branch, you can just specify the commit hash where it exists already. But of course it’s veeery unusable, I believe it must work the same way private actions work

And regarding the locations there’s one funny issue I found — you can’t have a reusable workflow file name to start with _ — that way the build will fail with an error that it can’t fetch the workflow file. I was hoping to have reusable workflows named this way so that workflows folder is in order. I like the idea of having reusable ones in some nested folder but if it’s not an option — having them named with _ prefix is good enough for me

How would I test a new version before merging if I hardcode the hash? I guess that’s what @outring meant by unusable. github.head_ref variable doesn’t work:

    uses: ./.github/workflows/reusable-builder.yml@${{ github.head_ref }}

invalid value workflow reference: version cannot have whitespace: ${{ github.head_ref }}

Update: and it works in

    name: CI Build
      - name: Compare IDs with ${{ github.base_ref }}

I use the branch I’m working on, not the hash. This gets annoying though if you need to have a workflow that calls the reusable workflow pass to merge, and want to keep using the workflow from the same branch (you have to merge twice in that case, once for the workflow and then to update the branch ref). After you’re done working on the reusable workflow using a fixed hash avoids having to switch branches, but means you need to explicitly update the ref after any future change to it.

1 Like