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.

[cmwilson21]

I think this has been covered and updated in a previous PR. I'm going to go ahead and close this now 💛

[airtonix]

@cmwilson21 in what PR?

[cmwilson21]

@airtonix Sorry, I may have been mistaken. I thought it was covered here. I'll reopen the issue.

My apologies! 🙈

[rlespinasse]

Disclaimer: I'm the author of the following action

In this action https://github.com/rlespinasse/github-slug-action, the behavior, described by @wickkidd, is possible with ${{ env.GITHUB_REF_NAME }} (read more).

- name: Inject slug/short variables
  uses: rlespinasse/github-slug-action@v4
  
- run:|
    echo "$GITHUB_REF_NAME will serve the internal behavior of GitHub Action"
    echo "${{ env.GITHUB_REF_NAME }} will serve the behavior of the GitHub Slug action"
  shell: bash

[cmwilson21]

👋 Hey folks! Thanks for all the great feedback in this issue. We had this as an open issue for anyone to work on, but after reviewing it, we are going to remove it from the help wanted board and discuss it a bit further.

Thanks again for all your input! 💖

[ryan-williams]

I have a step like this at the start of most workflows:

- run: echo "REF=${{ github.event.pull_request && github.head_ref || github.ref_name }}" >> $GITHUB_ENV

which lets me reference $REF in subsequent steps, to abstract over this head_ref/ref_name inconsistency.

[piotrekkr]

@ryan-williams Thanks for your example. I did not know there was ternary available in expression until I saw your example. Must have missed it in docs. Super handy to know about this.

//EDIT

Missed it probably because this was just one sentence with one example. There should be whole section just for ternary. I mostly used bash to make some stuff conditional and with ternary I don't have to do this any more. Such useful feature and it is not emphasized enough in docs...

// EDIT 2

Just checked git blame for docs and ternary operator docs were added 2 months ago... So that is why I missed it.

[igiona]

👋 Hey folks! Thanks for all the great feedback in this issue. We had this as an open issue for anyone to work on, but after reviewing it, we are going to remove it from the help wanted board and discuss it a bit further.

Thanks again for all your input! 💖

Does it mean you're on it, or that we're going to wait another year or two for this simple feature? By then, nearly everyone got a workaround in place...

[github-actions]

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

[mering]

3 days pass quickly nowadays...

[igiona]

A simple and generic way to get the current branch name is still required and would be much appreciated.
Thanks for considering this issue.

[piotrekkr]

I recently learned that even using some bash condition can fail to figure out the ref name for current workflow run. Idk how GitHub runners work but this workflow step fails randomly (like 10% of times). I have already sent an issue about this to GitHub support.

I have a workflow that is run on release and workflow_dispatch events. When this workflow is triggered by publishing new release it is randomly failing because GITHUB_REF and github.ref is not set. I use some bash logic to handle both release and workflows_dispatch GIT ref like this:

name: 01 - Deploy To Staging

concurrency: staging

on:
  release:
    types:
      - published
  workflow_dispatch:
    inputs:
      release_ref:
        description: "Release TAG"
        required: true

jobs:
  initialize:
    name: "Initialize deploy"
    runs-on: ubuntu-22.04
    timeout-minutes: 2
    outputs:
      ref: "${{ steps.version.outputs.ref }}"
    steps:
      - name: Get git ref
        id: git_ref
        run: |
          if [[ "${{ github.event_name }}" = "release" ]]; then
            echo "value=${{ github.ref }}" >> $GITHUB_OUTPUT
          else
            echo "value=${{ github.event.inputs.release_ref }}" >> $GITHUB_OUTPUT
          fi

# next steps are failing because they expect `steps.git_ref.outputs.value` or `GITHUB_REF` to be set

90% of times this works fine:

but in 10% of cases it fails:

Based on GitHub docs about github.ref it should be always set for both of those 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, this is the pull request merge 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 it is refs/pull/<pr_number>/merge, and for tags it is refs/tags/<tag_name>. For example, refs/heads/feature-branch-1.

Also this randomness is not just happening inside one repository workflow runs. When it happens it happens for multiple repositories at similar time.

Really weird stuff going on.

[piotrekkr]

If anyone is interested about my issue with getting current ref with release event, I got response from GitHub support:

Hello Piotr,

Thank you for reaching out to GitHub Support! I apologize for the delay here.

The behavior you're seeing is due to a known issue at this time affecting release event triggered runs. Our engineering team is tracking this behavior internally, and have confirmed that it has a fairly low repro rate - explaining the 90/10 split of times you noted seeing this issue.

Fix work will be planned and prioritized for this, but there is currently no concrete ETA. In the meantime, you can leverage data from the release payload to get the tag name (through github.event.release.tag_name) and set this up as a fallback value where you're calling github.ref.

In your provided snippet, this would look like the following:

if [[ "${{ github.event_name }}" = "release" ]]; then

echo "value=${{ github.ref || format('{0}{1}', 'refs/tags/', github.event.release.tag_name) }}" >> $GITHUB_OUTPUT

else

echo "value=${{ github.event.inputs.release_ref }}" >> $GITHUB_OUTPUT

fi

Since github.event.release.tag_name only returns the name of the tag minus the ref prefix, we're using the format function to add the prefix manually.

It seems for now this is low prio for them and as a workaround I should use

echo "value=${{ github.ref || format('{0}{1}', 'refs/tags/', github.event.release.tag_name) }}" >> $GITHUB_OUTPUT

to get release ref without random problems.

[cmwilson21]

@piotrekkr Thanks for coming back and reporting the convo with support! 👍