Clarify what path value to use when using an action in the same repository as the workflow

[gsrohde]

[maintainer edit] This issue is reserved for the MLH Fellowship program.

Code of Conduct

• [X] I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions

What part(s) of the article would you like to see updated?

This pertains to the Using an action in the same repository as the workflow example in the section on jobs.<job_id>.steps[*].uses.

The text shows that the value of uses when one want to use an action that is in the same repository as the workflow should be (something of the form) ./path/to/dir and then goes on to explain that this means "the path to the directory that contains the action in your workflow's repository." To any user of any shell, ./path/to/dir looks like a relative file path, but the question is then "relative to what?" Relative to the file for the workflow we are currently running? Relative to the root of the repository containing that workflow? (Based on the example that follows, which uses a uses value of ./.github/actions/my-action, this would seem a more likely guess.) Relative to the value of $GITHUB_WORKSPACE?

In the example given, these last two are the same—that is, $GITHUB_WORKSPACE is the root of the repository containing the workflow. But suppose we checked out the repository somewhere else, e.g.

jobs:
  my_first_job:
    steps:
      - name: Check out repository
        uses: actions/checkout@v3
        with:
          path: source_files
      - name: Use local my-action
        uses: ./.github/actions/my-action

It turns out the my-action action will no longer be found unless we change the value of uses to be relative to the value of $GITHUB_WORKSPACE; that is, we must modify the last line to be

        uses: ./source_files/.github/actions/my-action

This requirement should be made clear.

Another thing that isn't made clear is that we apparently must use the leading ./ when specifying the path. If one is thinking of this the way one usually thinks of file system paths, one might wonder why the value of uses can't simply be '.github/actions/my-action' (or, for my modified version, source_files/.github/actions/my-action). Presumably, the reason for the "leading ./" requirement is that it affords a clear distinction from the case where we are using an action from some (other) public repository: if we write uses: ./actions/heroku, the workflow will look for a file called action/heroku/actions.yml in our repository, whereas if we write uses: actions/heroku, it will look for a file called actions.yml in the root of the actions/heroku repository.

Could we use an absolute path with uses—for example, something like /home/runner/work/.../.github/actions/my-action? This could equally well be thought of as "the path to the directory that contains the action in your workflow's repository." I haven't tried this yet, but I suspect the answer is No.

Additional information

maintainer addition Anyone is welcome to open a PR following the instructions in https://github.com/github/docs/issues/19023#issuecomment-1269090748

[cmwilson21]

@gsrohde Thanks so much for opening an issue! I'll triage this for the team to take a look :eyes:

[github-actions[bot]]

Thanks for opening an issue! We've triaged this issue for technical review by a subject matter expert :eyes:

[github-actions[bot]]

This is a gentle bump for the docs team that this issue is waiting for technical review.

[github-actions[bot]]

This is a gentle bump for the docs team that this issue is waiting for technical review.

[github-actions[bot]]

This is a gentle bump for the docs team that this issue is waiting for technical review.

[cmwilson21]

Thank you for your patience as we work through our backlog 💛

[github-actions[bot]]

This is a gentle bump for the docs team that this issue is waiting for technical review.

[jc-clark]

Hey @gsrohde, thank you for contributing to this. Our team took a closer look at the articles you linked and the scenario you're describing and we agree. The documentation could use some improvements.

Overall, local actions must be a relative path (./). The path must be relative to the default working directory (github.workspace, $GITHUB_WORKSPACE). And if the action checks out a repository in a different location, the relative path for a local action will need to be updated (as you showed in your modified version).

More specifically:

1. the Using an action in the same repository as the workflow example section should mention that if the action checks out a different location than ./.github/workflows, the relative path after uses for the local action should be updated.
2. The Adding an action from the same repository documentation should also explain the same details
3. Since we will be including this information in more than one place, the above content should be put into a reusable file at /data/reusables/actions and then referenced by both Using an action in the same repository as the workflow and finding-and-customizing-actions.md

You or anyone else is welcome to create the PR to make these changes and we'll help review. Thank you!

[github-actions[bot]]

A stale label has been added to this issue becuase it has been open for 60 days with no activity. To keep this issue open, add a comment within 3 days.

[gsrohde]

I still think this is worth fixing. If I find some spare moments, I'll try to come up with some suggested rewording, if not a full-fledged pull request. But before doing that, however, I'll add a "notification comment" here first, in case someone from MLH Fellowship Spring '23 (classic) wants to have a go at it.

[github-actions[bot]]

A stale label has been added to this issue becuase it has been open for 60 days with no activity. To keep this issue open, add a comment within 3 days.

[gsrohde]

I still hope to get to fixing this (that is, if no one else does so first).

[cmwilson21]

@gsrohde Thanks for checking in on this one! We had this one reserved for for the MLH Fellowship program, but since the program has wrapped up, we've put it back on the OS help wanted board for anyone to contribute to ✨

[Jegan-Kunniya]

@cmwilson21, @gsrohde, @felicitymay - Folks, I find this issue interesting, and the recommendations could add a little bit more to conveying the message succinctly. I have picked this issue and will send a PR soon.

Through this comment on the issue, informing the community.