Workflow job execution doc should clarify that 'env' context is not available in job 'if' conditional

[neilotoole]

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-jobs/using-conditions-to-control-job-execution

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

The doc has an example:

name: example-workflow
on: [push]
jobs:
  production-deploy:
    if: github.repository == 'octo-org/octo-repo-prod'

I spent several hours trying to access env.MY_ENVAR, running into errors, before finally realizing that the env context cannot be accessed until after the job runner has been instantiated (which happens after the if guard has passed).

The doc should be updated to clarify that the env context is not available in the if conditional of a job.

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.

[cmwilson21]

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

[lecoursen]

Hi @neilotoole! Sorry you ran into trouble here, the solution is explained in a different article, "Environment variables":

Environment variables are always interpolated on the virtual machine runner. However, parts of a workflow are processed by GitHub Actions and are not sent to the runner. You cannot use environment variables in these parts of a workflow file. Instead, you can use contexts. For example, an if conditional, which determines whether a job or step is sent to the runner, is always processed by GitHub Actions. You can use a context in an if conditional statement to access the value of an environment variable.

I can see how it would be helpful for readers to introduced to that same information in the "Using conditions to control job execution" article, so let's add a note there with a brief mention that you can use contexts to access the value of an environment variable, and a link to that section of "Environment variables" for the full details. You or anyone else is welcome to open a PR doing so! ⚡

[neilotoole]

@lecoursen Thanks for getting back to me. I tried repeatedly to access an envar in the job if conditional, but it always failed. Using the same syntax, I was able to access the envar in a step if conditional. My conclusion was that it was not possible to access envars in the job if conditional. If I'm wrong about that, could you provide an example to me, and I'll test it out?

[lecoursen]

👋🏻 @neilotoole, please contact our support team for troubleshooting. Thanks!