Clarify what path value to use when using an action in the same repository as the workflow #19023
Description
Code of Conduct
- 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 #19023 (comment)