Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: describe conditional values #31252

Merged
merged 5 commits into from
Mar 5, 2024
Merged

feat: describe conditional values #31252

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
5917b79
refactor: describe an acceptable `if` value
deemp Jan 24, 2024
b46ddeb
Revert "refactor: describe an acceptable `if` value"
deemp Jan 26, 2024
596ce33
feat: explain coercion of falsy and truthy values
deemp Jan 26, 2024
174cfa5
Update content/actions/learn-github-actions/expressions.md
SiaraMist Mar 5, 2024
479d72e
Merge branch 'main' into refactor-explain-if-condition
SiaraMist Mar 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion content/actions/learn-github-actions/expressions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ versions:

You can use expressions to programmatically set environment variables in workflow files and access contexts. An expression can be any combination of literal values, references to a context, or functions. You can combine literals, context references, and functions using operators. For more information about contexts, see "[AUTOTITLE](/actions/learn-github-actions/contexts)."

Expressions are commonly used with the conditional `if` keyword in a workflow file to determine whether a step should run. When an `if` conditional is `true`, the step will run.
Expressions are commonly used with the conditional `if` keyword in a workflow file to determine whether a step should run. When an `if` conditional is `truthy` (in [JavaScript sense](https://developer.mozilla.org/en-US/docs/Glossary/Truthy)), the step will run. All values are `truthy` except for `false`, `0`, `-0`, `0n`, `""`, `''`, `null`, `undefined`, `NaN`. You can evaluate an `!!<expression>` (e.g., in your browser console) to check whether the `<expression>` is `truthy`. For example, `!!"false"` produces `true`, so `"false"` is `truthy`.

Copy link
Contributor

@ferdnyc ferdnyc Jan 26, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This... isn't correct at all.

The workflow is parsed in a string context (except for numerals and booleans), so JavaScript truthiness is irrelevant. There's no way to define a true JavaScript NaN or undefined in YML, you end up with the strings 'NaN' or 'undefined'. Nearly any string will evaluate true.

In this workflow:

    strategy:
      matrix:
        runme:
          - NaN
          - undefined
          - yes
          - no
          - false
          - 0
          - 1
          - -0

    steps:
      - name: true-path
        if: matrix.runme
        run: echo "${{ matrix.runme }} evaluates true"
      - name: false-path
        if: '! matrix.runme'
        run: echo "${{ matrix.runme }} evaluates false"

...The only matrix.runme values for which false-path will be executed are false and 0. (And -0, technically, but that's only because it's interpreted as 0. There's no distinction in YAML.) All of the others will evaluate true.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh, sorry, null is also a valid YAML primitive, and it will also evaluate false.

Honestly, I think this is pretty well explained in the Literals section of the Expressions docs.

Copy link
Contributor Author

@deemp deemp Jan 26, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. I ran the suggested job (link). I can confirm that the falsy values are false, 0, -0, "", '', null. I can't see where these values are listed in the Literals section. What do you think about just extending the boolean docs?

    Data type Literal value
    boolean falsy (false, 0, -0, "", '', null) or truthy (true and other non-falsy values)

  2. I believe it's necessary to mention in the if docs that it expects a boolean and will run a step if the boolean is truthy. BTW, the docs already mention a truthy value (link), but don't explain it.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated the PR

{% data reusables.actions.expressions-syntax-evaluation %}

Expand Down