Document truthiness handling for expressions

[jsoref]

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?

https://docs.github.com/en/actions/learn-github-actions/expressions

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

Some part of the page should explain how:

if: ${{ vars.FOO }}

works. Specifically, if vars.FOO isn't set, that's presumably treated as the equivalent of an empty something (string?).

if vars.FOO is set, it's presumably treated as a string.

Note that I'm using vars above, but the same applies for anything that would naturally be stringy (env, inputs(that are stringy), secrets, outputs,....)

Are all non-empty strings true?

Is the string "0" true?
Is the string "false" true?

There's some prose that says that when comparing two things, if they're of different types, they're converted to numbers.

But it isn't particularly clear if, if: ${{ some_expression }} is treated as if: ${{ (some_expression) == true }} which thus results in strings being converted to numbers and true being converted to a number.

Additional information

[maintainer edit]
Content plan here

[cmwilson21]

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

[jsoref]

@cmwilson21 ?

[cmwilson21]

@jsoref - reopened! Sorry about that! 👍

[hubwriter]

@jsoref - Thanks for raising this.

We've added the following to that article recently:

Using the ${{ }} expression syntax turns the contents into a string, and strings are truthy. For example, if: true && ${{ false }} will evaluate to true.

I think this answers you in situations where you enclose the expression in an if statement in ${{ ... }} and so it gets evaluated as a string. Hopeful "strings are truthy" clarifies that all non-empty strings, including "false" and "0" are true.

It would, however, be useful to be clear, in the article about if https://docs.github.com/en/actions/using-jobs/using-conditions-to-control-job-execution, what is considered true and false where ${{ ... }} are not used - i.e. that an unset variable equates to false, and a variable containing any string (even “false” or the string “0") equates to true. I'm guessing that a variable set to the integer zero equates to false, and to any other number true - but I'm not sure. It would be easy to check though.

I think it would be helpful to add a little paragraph (perhaps a subsection) in https://docs.github.com/en/actions/using-jobs/using-conditions-to-control-job-execution stating explicitly what evaluates to true and false, for the avoidance of doubt.

It would be great if someone would care to pick this up, do a little testing to establish the situation, and write this up in a PR. I'll label this issue help wanted.

[SoundaryaKoutharapu]

Hi @hubwriter, @cmwilson21

I'd like to get started with this issue.
Can you confirm, is this fine to proceed with PR.

Determining Truthiness and Falseness in GitHub Actions

In GitHub Actions, understanding when a value is considered "true" or "false" is crucial for crafting effective conditional statements. The evaluation of truthiness and falsiness in GitHub Actions can be summarized as follows:

${{ ... }} Expressions:
When you enclose an expression within ${{ ... }}, the content is treated as a string, and all strings are considered "truthy." This means that, in ${{ ... }} expressions, values like "false" and "0" are considered "true."

Unset Variables:
An unset variable, one that has not been defined or lacks a value, is considered "false."

String Variables:
Any variable containing a string, including the string "false" or "0," is considered "true."

Numeric Variables:
A variable set to the integer zero is considered "false."
Any other numeric value, including non-zero integers or floating-point numbers, is considered "true."

[cmwilson21]

@SoundaryaKoutharapu Thanks for your interest! I think it'll be fine to proceed with the PR, and then we can suggest any edits or updates in the review process ✨

[jsoref]

I think an empty string ('') is false...