Actions workflow syntax: `if` without expression syntax `${{ }}` can result in YAML syntax error

[victorlin]

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?

Anything that uses reusables.actions.expression-syntax-if, which states:

When you use expressions in an if conditional, you may omit the expression syntax (${{ }}) because GitHub automatically evaluates the if conditional as an expression.

So, at least the following:

1. https://docs.github.com/en/actions/learn-github-actions/expressions
2. https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idif

What changes are you suggesting?

These articles suggest that ${{ }} can always be omitted from an if conditional. However, that is not the case since this results in a YAML syntax error (evidence):

if: !false || false

Wrapping it in ${{ }} allows the expression to be evaluated properly (evidence):

if: ${{ !false || false }}

I suggest changing the wording to highlight this limitation.

Additional information

No response

### Tasks

[cmwilson21]

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

[victorlin]

A nice explanation from @tsibley in nextstrain/.github#33 (comment):

the reason ${{ }} is "required" despite the docs saying it isn't is because the file still has to be valid YAML syntax. While strings in YAML can normally be unquoted, there are exceptions where quotes are required, such as when specific YAML metachars are present in the string. The leading !... | construct here in the condition is the culprit that requires quoting, as it's a type tag (!...) and block scalar start (|). So the ${{ }} changes that by making the !... no longer a type tag, and thus the | no longer a block scalar start. The point is that using normal YAML quoted strings:

if: "!(inputs.run-on-nextstrain-only) || github.repository_owner == 'nextstrain'"

works just as well as an unquoted ${{ ... }}.

[lucascosti]

Thanks for opening this issue, @victorlin!

Yep, as you discovered in your comment, you can't begin YAML values with some special characters unless you quote them.

This applies to all YAML values, not just for GitHub Actions or the if key, so a doc update probably isn't required here.