String to boolean conversion in workflow expressions

[lelegard]

Hi,

In a workflow, a step wants to produce a boolean value in its outputs. Since the outputs are written in the text file $GITHUB_OUTPUT, we write a text line such as:

  check_version:
    outputs:
      rebuild: ${{ steps.check.outputs.rebuild }}
    steps:
    - id: check
      run: echo "rebuild=true" >>$GITHUB_OUTPUT

Then, if we want to use that output value in boolean expressions, sometimes it works, sometimes it doesn't.

For instance, in the same job, this works in a subsequent step:

    - if: steps.check.outputs.rebuild

However, in a subsequent job, it doesn't:

  linux:
    needs: [check_version]
    uses: ./.github/workflows/release-linux.yml
    with:
      build: ${{ needs.check_version.outputs.rebuild }}

The input parameter build is defined as boolean in the called workflow release-linux.yml.

We get the following error message when running the workflow:

.github/workflows/nightly-build.yml (Line: 94, Col: 14): Unexpected value 'true'

The following condition works:

      build: ${{ needs.check_version.outputs.rebuild == 'true' }}

Why is the output value sometimes accepted as a boolean and sometimes not?

Can we force some kind of conversion to boolean? Something like ${{ boolean(needs.check_version.outputs.rebuild) }}.

When we generate an input in a step using $GITHUB_OUTPUT, is there a way to type it as a boolean? It seems that they are all interpreted as string.

[KarinaGante]

Hi!

Great question — you’ve pinpointed one of the subtle (and confusing) behaviors of GitHub Actions.

All values written to $GITHUB_OUTPUT are treated as strings, even if you write true, false, 1, or 0.

That’s why:

• In if: expressions, steps.check.outputs.rebuild works because it's being evaluated in a boolean context, where "true" (a non-empty string) is truthy.

• But in a with: input (like passing build: ${{ needs.check_version.outputs.rebuild }} to a reusable workflow), the system expects a true boolean type, not a string. Hence the error.

You're already doing the right thing by using:

build: ${{ needs.check_version.outputs.rebuild == 'true' }}

This forces a proper boolean conversion, and is currently the best and most reliable way to pass a string-as-boolean to inputs typed as boolean.

Can we force type in $GITHUB_OUTPUT?

Unfortunately, no. There's no way to set a native boolean type in $GITHUB_OUTPUT — it’s all strings under the hood.

If you plan to use the output in multiple places as a boolean, consider defining a helper expression:

build: ${{ needs.check_version.outputs.rebuild == 'true' }}

Or alternatively:

build: ${{ fromJSON(needs.check_version.outputs.rebuild) }}

fromJSON('true') converts the string 'true' into the actual boolean true.

[lelegard]

Thanks @KarinaGante, this is really helpful.

Would that work, to force the output as a boolean value from the beginning:

  check_version:
    outputs:
      rebuild: ${{ fromJSON(steps.check.outputs.rebuild) }}
    steps:
    - id: check
      run: echo "rebuild=true" >>$GITHUB_OUTPUT

Then, needs.check_version.outputs.rebuild would be a boolean everywhere.

I know, I could try. I am just reluctant to trigger the whole CI/CD stuff of a push operation to test some random thing and I prefer to ask first.

[KarinaGante]

You're very welcome — glad it helped! 😊

About your follow-up question:

Would that work, to force the output as a boolean value from the beginning:

check_version:
      outputs:
        rebuild: ${{ fromJSON(steps.check.outputs.rebuild) }}

Unfortunately, no — that won’t work as expected.

The key point is that outputs in a job context (like check_version.outputs.rebuild) can only reference raw strings written to $GITHUB_OUTPUT by a step. So even if you wrap it with fromJSON(...) in the outputs: block, that line is just forwarding the string from the step — GitHub doesn’t evaluate expressions or convert types at that point.

In other words, this:

outputs:
  rebuild: ${{ fromJSON(steps.check.outputs.rebuild) }}

…still just passes a string to the next job. So when the next job receives rebuild: "true" as a string and expects a boolean, it will fail unless explicitly converted.

Correct way to convert to boolean:

The proper place to force the value into a boolean is at the point of use, like:

build: ${{ needs.check_version.outputs.rebuild == 'true' }}

or

build: ${{ fromJSON(needs.check_version.outputs.rebuild) }}

`fromJSON('true')` → `true` (actual boolean)
`fromJSON('false')` → `false`

Want to test without triggering full CI/CD?

That’s a smart concern. Here's a safe approach:

• Create a test branch, like pages-test or ci-sandbox.
• Modify your workflow to include a condition that only runs if it's on that branch:

on:
  push:
    branches:
      - ci-sandbox

• Alternatively, add a condition to your job:

if: github.ref == 'refs/heads/ci-sandbox'

This way, you can freely experiment with your workflow logic, fromJSON, outputs, and so on — without touching production or triggering full deploys.

[lelegard]

Thanks @KarinaGante, understood.

In if: expressions, steps.check.outputs.rebuild works because it's being evaluated in a boolean context, where "true" (a non-empty string) is truthy.

One last question. In that case, the string "false" being non empty, it is also interpreted as the boolean true. This means that if: steps.check.outputs.rebuild is syntactically accepted in the same job but is incorrect and misleading because it interprets the string "false" as boolean true.

[KarinaGante]

You're absolutely right — great observation!

In GitHub Actions, expressions like:

if: steps.check.outputs.rebuild

are evaluated in a truthy/falsy context. Since "false" is a non-empty string, it’s considered truthy — meaning the condition will still evaluate to true, even though the intent was likely the opposite.

That’s why relying on the raw string without explicit comparison can lead to misleading behavior. To avoid that confusion, it's always best to compare explicitly, like:

if: steps.check.outputs.rebuild == 'true'

This way, "true" evaluates to true, and "false" evaluates to false, just as you'd expect.

Thanks again for the great follow-up — you're clearly digging deep into how GitHub Actions works, which is awesome!

If everything’s clear now, feel free to mark the discussion as answered so others can benefit from it too.

And of course, if more questions come up, don’t hesitate to ask — happy to help anytime!

[lelegard]

Thanks, answer marked.

If anyone is interested, here is the fixed workflow.