Bug: job.step.if parsing not as documented; misleading error message

Check out this build:

image

GoLand tells me this is valid YAML and conforms to the GitHub Actions Workflow Schema.
So what’s going on here?

Turns out we have two problems.

  1. The error is not actually in line 65, it’s in 66. Forgot to add one from the zero-based array? Whoops.

  2. if doesn’t parse as specified:

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

    Only, if: contains(...) parses fine, whereas if: !contains(...) does not.

Workaround: Fall back to if: ${{ !contains(...) }}

@reitzig,

Thanks for your feedback.
I also can reproduce the same issue on my side.
I have reported this issue to the appropriate engineering team for further investigation and evaluation. If they have any progress, I will notify you in time, and sometimes the appropriate engineers may directly reply you here.

As the workarounds, you also can use the Equal (==) or Not equal (!=) operator in the if conditional.

if: contains(matrix.os, 'windows') == false

OR

if: contains(matrix.os, 'windows') != true

About the following expression syntax you mentioned,

if: ${{ !contains(matrix.os, 'windows') }}

I will confirm with the engineering team whether this is the right syntax for the design when using the Not (!) operator in the if conditional.

2 Likes

A leading “!” indicates a YAML tag

${{ }} helps to avoid the leading ! being interpreted as tag syntax.

Quoting would probably also work. For example: if: "!contains(matrix.os, 'windows')"

We updated the examples in the docs to always use ${{ }}.

3 Likes

Thank you for your help, @ericsciple .

@reitzig,
I have tested the expressions below according to @ericsciple’s reply, all of them can work fine as expected.

  1. Using ${{. . .}}, recommended expression.
if: ${{ !contains(matrix.os, 'windows') }}
  1. Using (. . .)
if: (!contains(matrix.os, 'windows'))
  1. Using double quotes (". . .")
if: "!contains(matrix.os, 'windows')"

Thanks for the responses. There is indeed no problem expressing the desired condition. However, the documentation is still misleading.

jobs.<job_id>.if

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

Operators

image

Combining two two, a novice will probably run into the same issue I did, compose

 if: !<something>

and get a very much unhelpful error. Expecting the user to

  1. have YAML tags in mind – a feature I for one have never seen used before, or even mentioned – and then to
  2. correctly deduce the potential for conflict – in my example, it seems obvious that no type follows, so there’s no actual amiguity, the parser just isn’t smart enough –

seems a bit of a stretch, in my opinion.

I don’t have a good proposal for how to fix the first piece of documentation. Adding “unless the YAML parser gets confused” would be correct but not actionable. Adding “unless it starts with an ! operator” would be correct but undoubtedly miss another special case.

Maybe removing this syntax sugar – i.e. always require ${{ ... }} wrappers – would result in the clearest syntax, but that would be a breaking change.


Also, line numbers are still off-by-one (as far as I can tell); should I create a separate post for that?

@reitzig,

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

I agree that this description may be misleading.

However, I also noticed that 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 (${{ }}).

Also, line numbers are still off-by-one (as far as I can tell); should I create a separate post for that?

Yes, please open a new ticket for each different question.

1 Like

Done

(Ticket? :thinking: Curious, why does GitHub of all organizations use a discussion board for issue tracking? :wink: )

@reitzig,

Depending on the situations, we do not always discuss in the GitHub Actions section.

  1. If you have any question related to workflow configuration, such as syntax, GitHub-hosted runners, or building actions, you can open a new ticket in the GitHub Community Support’s GitHub Actions board to ask help, or look for the existing tickets related to your question.

  2. If you find bugs or issues occur on GitHub Actions, you also can report those in the GitHub Actions board. We will check these issues and open issue tickets in the appropriate repositories to report the them to the appropriate engineering team for further investigation and evaluation. You also can view the progress of the recent reported incidents from GitHub Status.

  3. If you have feedback or feature requests for GitHub Actions, you can share those in the Feedback form for GitHub Actions.

1 Like