GITHUB_REF and GITHUB_REF_NAME examples in Actions docs unclear

[oofnikj]

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/learn-github-actions/environment-variables#default-environment-variables

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

GITHUB_REF and GITHUB_REF_NAME show example values of refs/heads/feature-branch-1 and feature-branch-1 respectively. However this is inconsistent with the values populated in the case of a PR-triggered workflow.

Given the description and example, one would expect to see the branch that triggered the workflow when running a PR-triggered workflow. Instead these variables are populated by values like refs/pull/26/merge and 26/merge respectively. The variable that contains the desired data in this case is actually GITHUB_HEAD_REF.

The documentation should be updated to more accurately describe the content of GitHub Actions predefined variables.

Additional information

No response

[welcome]

Thanks for opening this issue. A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.

[ramyaparimi]

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

[skedwards88]

Thanks for opening this issue! You proposal to add/clarify this information sounds good. You or anyone else is welcome to open a PR to address this. (Note that this was partially addressed in #15304)

[wickkidd]

Why should GITHUB_REF_NAME be different for a PR? If it's supposed to return the source branch (a very useful thing) then it should do so regardless of the context. To me this seems more like a bug than bad documentation.

[Kurt-von-Laven]

It would certainly be more helpful for our use case to have a simpler way to get the branch name regardless of context. Here is the snippet of Python code we are using to get the branch name now.