Variables environment variable example is misleading

[kaylareopelle]

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/variables#defining-environment-variables-for-a-single-workflow

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

I would like the example within Defining environment variables for a single workflow to be updated to use accurate syntax.

Additional information

I received an "Invalid workflow file" error when I tried to use the presented syntax while running ubuntu-22.04, which I believe is ubuntu-latest.

I tried:

$DESTINATION_REPO
"$DESTINATION_REPO"
${{ $DESTINATION_REPO }}

And got the same error each time. Only ${{ env.DESTINATION_REPO }} worked.

[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.

[cmwilson21]

@kaylareopelle Thank you for opening an issue and linking it to your PR! ✨

[hubwriter]

@kaylareopelle - Thanks for raising this issue and the PR.

I'd need to see your workflow to understand why using the environment variable syntax didn't work for you. However, the workflow example you are suggesting changing does work as reproduced so I don't think we'd want to change that.

The "Using contexts to access variable values" documentation, that's linked to from the passage you suggest changing, explains how the parts of a workflow processed on GitHub (before the workflow is processed on the runner) and can't use runner environment variables (like $NAME) but instead need to use contexts (like ${{ NAME }}. I suspect this what you were coming up against.

I'll suggest in your PR how we could clarify the docs.

[kaylareopelle]

Thanks for your patience! This issue happened both in with and run parts of a step. The environment variables were defined at the top of the workflow like this:

env:
  BRANCH_NAME: ruby-config-updates
  DESTINATION_REPO: kaylareopelle/docs-website

Here's an example using the "with" key:

      - name: Checkout docs website repository
        uses: actions/checkout@v3
        with:
          repository: ${{ env.DESTINATION_REPO }} 
          token: ${{ secrets.KAYLA_CONFIG_DOCS }} 

The repository: ${{ env.DESTINATION_REPO }} code is where I tried the syntaxes:

• $DESTINATION_REPO
• "$DESTINATION_REPO"
• ${{ $DESTINATION_REPO }}

I could only get the env. version to work.

The same is true of the BRANCH_NAME variable in the following run command:

      - name: Build delete command
        run: echo "delete_file=git push origin --delete ${{ env.BRANCH_NAME }} --force" >> $GITHUB_ENV

Here's the full job for that one:

  delete_branch_on_fail:
    name: Delete branch on fail
    needs: [regenerate_config_docs]
    runs-on: ubuntu-22.04
    if: failure()
    steps:
      - name: Checkout agent repository
        uses: actions/checkout@8f4b7f84864484a7bf31766abe9204da3cbe65b3 # tag v3.5.0
      - name: Checkout docs website repository
        uses: actions/checkout@v3
        with:
          repository: $DESTINATION_REPO
          token: ${{ secrets.KAYLA_CONFIG_DOCS }}

      - name: Build delete command
        run: echo "delete_file=git push origin --delete $BRANCH_NAME --force" >> $GITHUB_ENV

Could you help me understand why this usage is different from the example?

[hubwriter]

@kaylareopelle - Thanks for the extra details.

I'm not an expert on this, so I've asked for someone from our Actions channel to take a look at this for you.

[kaylareopelle]

Thank you!

[joshmgross]

👋 Hey @kaylareopelle,

I agree the docs are misleading here - the $VARIABLE_NAME syntax will only work in code executed by a bash shell (i.e. a run step on a Linux or macOS runner). It won't work on a Windows runner (which needs to use the Powershell syntax $env:VARIABLE_NAME) or other parts of a workflow.

In all other parts of a workflow, you'll want to use the Actions expression block ${{ }} and the env context directly.

I would expect run: echo "delete_file=git push origin --delete $BRANCH_NAME --force" >> $GITHUB_ENV to work though. The example in the docs does work as is, it just doesn't show how to use env variables outside of a bash shell.

name: Greeting on variable day

on:
  workflow_dispatch

env:
  DAY_OF_WEEK: Monday

jobs:
  greeting_job:
    runs-on: ubuntu-latest
    env:
      Greeting: Hello
    steps:
      - name: "Say Hello Mona it's Monday"
        run: echo "$Greeting $First_Name. Today is $DAY_OF_WEEK!"
        env:
          First_Name: Mona

https://github.com/joshmgross/actions-testing/actions/runs/5788433947/job/15687418090

[hubwriter]

@joshmgross - Many thanks.

Below the example in the docs we say this:

Because runner environment variable interpolation is done after a workflow job is sent to a runner machine, you must use the appropriate syntax for the shell that's used on the runner. In this example, the workflow specifies ubuntu-latest. By default, Linux runners use the bash shell, so you must use the syntax $NAME. If the workflow specified a Windows runner, you would use the syntax for PowerShell, $env:NAME. For more information about shells, see "Workflow syntax for GitHub Actions."

Perhaps the fix to this issue is just to highlight this paragraph more by putting it in a Note box.

[kaylareopelle]

Hi @joshmgross, @hubwriter! 👋

Thanks for chiming in here. After further testing run: echo "delete_file=git push origin --delete $BRANCH_NAME --force" >> $GITHUB_ENV works. I'm not sure what made me think otherwise.

My central point of confusion was summarized nicely by @joshmgross:

the $VARIABLE_NAME syntax will only work in code executed by a bash shell (i.e. a run step on a Linux or macOS runner). It won't work on a Windows runner (which needs to use the Powershell syntax $env:VARIABLE_NAME) or other parts of a workflow.

In all other parts of a workflow, you'll want to use the Actions expression block ${{ }} and the env context directly.

The excerpt shared by @hubwriter may benefit from putting it in a Note box. However, I remember trying to decipher that paragraph. I assumed any part within a job that runs-on: ubuntu-latest could use the $VARIABLE_NAME syntax. I did not understand that runner meant only the run: part, and not the uses: part.

I'm happy to make another attempt at revision. I'm also happy to let someone from the GitHub team make revisions. Which would you all prefer?

[hubwriter]

I'm happy to make another attempt at revision.

Thanks @kaylareopelle. If you could revise your PR that would be great. 👍

[hubwriter]

@kaylareopelle - Some more information. I discussed this outside of this issue and Josh's comments are useful. It would be great if you could revise the article as Josh suggests:

hubwriter:
My take on this is that the paragraph under the example explains this

joshmgross:
It does explain this, but I think it's worth mentioning how to use env variables outside of a run step within an Actions expression.

We could even update that example to show passing an env value to an action

But please let me know (e.g. @ mention me on the PR) if you'd like any help with this.