The gihub.ref description is confusing and incorrect, particularly for PRs

[jonnybolton16]

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/reference/workflows-and-actions/contexts#github-context

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

The description for github.ref is confusing, misleading and incorrect, particularly for PR events.

The fully-formed ref of the branch or tag that triggered the workflow run. For workflows triggered by push, this is the branch or tag ref that was pushed. For workflows triggered by pull_request that were not merged, this is the pull request merge branch. If the pull request was merged, this is the head branch. For workflows triggered by release, this is the release tag created. For other triggers, this is the branch or tag ref that triggered the workflow run. This is only set if a branch or tag is available for the event type. The ref given is fully-formed, meaning that for branches the format is refs/heads/<branch_name>. For pull requests events except pull_request_target that were not merged, it is refs/pull/<pr_number>/merge. pull_request_target events have the ref from the base branch. For tags it is refs/tags/<tag_name>. For example, refs/heads/feature-branch-1.

Firstly, it's quite hard to follow the different branching logic of that parapgrah. Can this be formatted better, e.g. with nested bullet points?

Secondly, particularly for PR events, the logic is quite unclear, and incorrect in some places. The description mentions

pull requests events

but doesn't define them what these are. Is it the following subset of triggers?

• pull_request
• issue_comment
• pull_request_review
• pull_request_review_comment
• pull_request_target

Assuming this is the case, my understanding of the logic is as follows:

1. pull_request events with a closed activity type that were merged: github.ref = refs/heads/<head_branch>
2. All other pull_request events: github.ref = refs/pull/<pr_number>/merge
3. All pull_request_target events (potentially excluding merged events): github.ref = refs/heads/<base_branch>
4. issue_comment, pull_request_review and pull_request_review_comment (and potentially merged pull_request_target) events: github.ref = refs/pull/<pr_number>/merge

Problems to highlight:

1. It's unclear whether "pull requests events except pull_request_target that were not merged" includes merged pull_request_target events. My tests suggest it doesn't; merged pull_request_target events show refs/heads/main, not refs/pull/<pr_number>/merge. What is this line trying to say?
2. On a merged pull_request event, my tests show <base_branch>, not <head_branch>. There is a mistake in the description.
3. For pull_request_target events, regardless of PR direction (main -> test or test -> main), my tests show refs/heads/main. Is it always the repo default, not the PR base?
4. My tests show issue_comment events use refs/heads/main (regardless of PR direction), not refs/pull/<pr_number>/merge. Are these events not part of the PR logic? Does it always use the repo default?
5. If we're being picky, there's a case to be made that "workflows triggered by pull_request that were not merged" means "closed and not merged" - meaning other activity types might not be included in the list. This could be worded better

Is the following summary more accurate?

• All pull_request_target events: refs/heads/<default_branch>
• Merged pull_request events: refs/heads/<base_branch>
• All other pull_request events, and all pull_request_review and pull_request_review_comment events: refs/pull/<pr_number>/merge
• issue_comment events: refs/heads/<default_branch>

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.

[Sharra-writes]

@jonnybolton16 We do like bullet points these days. I will ask the rest of the team to see if we can improve the formatting without getting the Actions team involved, since that's a bit of a process right now, and it will go faster if we can keep it in the docs team.

[github-actions]

A stale label has been added to this issue, because it has been open for 30 days with no activity. If you think this issue should remain open, please add a new comment.

[jonnybolton16]

Is there any update on this?

[Sharra-writes]

@jonnybolton16 The only update is that I had to get Actions involved, and now I'm waiting.