Document how to skip a step if a secret isn't present

[jsoref]

What article on docs.github.com is affected?

https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idstepsif
https://docs.github.com/en/actions/reference/context-and-expression-syntax-for-github-actions
https://docs.github.com/en/actions/reference/encrypted-secrets

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

• Something in the if set should mention that secrets. isn't available
• Something in the context set should mention that secrets. isn't available in if
• Something in the three should explain how to work around this

Additional information

It is common for projects to include a secret for deploying things and an action that uses that secret.

When one forks that repository, the secret won't be present and the workflow will break.

This experience is incredibly painful.

With just a bit of extra code in a workflow, the ❌ 's go away. But, w/o documentation on how to do it, 99% of workflow authors won't.

Here's an example which fixed one (of a number of failing workflows):
jsoref/argo-cd@ae52e40

      - name: deploy
        if: ${{ github.event_name == 'push' && env.HAVE_PERSONAL_TOKEN == 'true' }}
        uses: peaceiris/actions-gh-pages@v2.5.0
        env:
          HAVE_PERSONAL_TOKEN: ${{ secrets.PERSONAL_TOKEN != '' }}
          PERSONAL_TOKEN: ${{ secrets.PERSONAL_TOKEN }}

[janiceilene]

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

[skedwards88]

Thank you for opening this issue! I have modified your suggestion for how to change the docs:

1. We document that the secrets context is not available in if statements in the "Context availability" section of "Context and expression syntax for GitHub Actions", so I recommend leaving this article as is.

2. I think you are right that we could additionally call this out in the "if" sections in Workflow syntax for GitHub Actions. For example, adding a sentence like

   Not all contexts are available to if statements.

   before

   For more information, see "Context and expression syntax for GitHub Actions."

3. Additionally, I think you are right that users would find a workaround helpful given how many issues and discussions have been opened with this request. An example could be added to the end of the "Using encrypted secrets in a workflow" section in "Encrypted secrets", prefaced with a sentence describing the use case. Here is a simplified example:

on: push
jobs:
  my-jobname:
    runs-on: ubuntu-latest
    env:
       MY_SECRET: ${{ secrets.MY_SECRET }}
    steps:
      - if: ${{ env.MY_SECRET }}
        run: echo "I have the secret!"

You or anyone else is welcome to open a PR to make these changes.

[KingofAngma]

/ihave#noidea /false

[jsoref]

I might do it at some point, but I'm hoping someone will pick it up first...