${{ / }} wrappings around Job status check functions could be omitted

[jsoref]

What article on docs.github.com is affected?

https://docs.github.com/en/actions/reference/context-and-expression-syntax-for-github-actions#job-status-check-functions

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

https://docs.github.com/en/actions/reference/context-and-expression-syntax-for-github-actions#example-6

 if: ${{ success() }}

https://docs.github.com/en/actions/reference/context-and-expression-syntax-for-github-actions#example-7

if: ${{ always() }}

https://docs.github.com/en/actions/reference/context-and-expression-syntax-for-github-actions#example-7

if: ${{ cancelled() }}

https://docs.github.com/en/actions/reference/context-and-expression-syntax-for-github-actions#example-9

 if: ${{ failure() }}

Additional information

Technically the ${{ and }} here are optional

https://docs.github.com/en/actions/reference/context-and-expression-syntax-for-github-actions#about-contexts-and-expressions

When you use expressions in an if conditional, you may omit the expression syntax (${{ }}) because GitHub automatically evaluates the if conditional as an expression, unless the expression contains any operators. If the expression contains any operators, the expression must be contained within ${{ }} to explicitly mark it for evaluation. For more information about if conditionals, see "Workflow syntax for GitHub Actions."

It'd be nice if the document helped people internalize when they need to / don't need to use ${{/}}, by not using ${{/}} in places where they aren't necessary.

[Simran-B]

It's true, but it is a bit easier to understand that the if key accepts a GitHub Actions expression thanks to the ${{ }} wrapper, which you need in all other places. There are also some corner cases that need it, sort of. Here is an example:

if: !contains(matrix.os, 'Windows')

You have an error in your yaml syntax …

https://github.community/t/bug-job-step-if-parsing-not-as-documented-misleading-error-message/118699

A leading exclamation mark is reserved for tagging in YAML. The expression wrapper happens to make this a legal string again because the exclamation mark will no longer be in the first position and the dollar sign doesn't have any special meaning.

There are other ways to resolve the issue, however:

• Use a double-quoted flow scalar
  if: "!contains(matrix.os, 'Windows')" (may need to escape " in the expression as \")
• Use a single-quoted flow scalar (requires ' in the expression to be escaped as '')
  if: '!contains(matrix.os, ''Windows'')'
• Use a folded block scalar with block chomping. Can also be used to wrap long expressions.

  if: >-
   !contains(matrix.os, 'Windows')
  

• Change the expression so that no leading ! is required
  if: (!contains(matrix.os, 'Windows'))
if: contains(matrix.os, 'Windows') == false
if: contains(matrix.os, 'Windows') != true

Anyway, quoting from the community post:

[…] after the recent several updates of the docs, we can see the if conditionals in all the examples have been changed to use the expression syntax (${{ }}). Although most of the examples still can omit the expression syntax.

I think the purpose of these updates is to gradually introduce a set of standardized and general expression syntax, namely the expression syntax (${{ }}).

It comes down to whether it should be kept simple by always using the wrapper in examples and leaving it to frequent users to read that it can be omitted in many cases, or to omit it wherever possible but requiring users to learn about some of the YAML syntax details. The latter might have the positive side effect that it becomes easier to compose conditions for beginners - I saw several posts where people tried something along if: ${{ 'foo' == 'foo' }} && 'bar' == 'bar. On the other hand, it becomes more obvious whether you attempt to use nested expressions (not supported) if the overall expression is always wrapped:

if: github.ref == refs/heads/${{env.default_branch}}

vs.

if: ${{ github.ref == refs/heads/${{env.default_branch}} }}

(The actual solution is to use format().)

https://github.community/t/use-environment-variables-in-if-statement/164864

[janiceilene]

Thanks for opening an issue @jsoref and thanks for all of the additional context @Simran-B! I'll triage this for the team to take a look 👀

[jsoref]

Yes, thanks @Simran-B.

Even if my suggested change isn't made, I think some of the items that @Simran-B mentioned should be added.

[lecoursen]

Thanks @jsoref. For consistency, we'll keep the wrappings as is.