GitHub Actions Expressions: Operators, Functions and Gotchas
The rule behind most broken if: conditions: any non-empty string is truthy, including the string "false". A condition comparing to a boolean-looking output is frequently always true.
GitHub Actions expressions look like a small programming language and behave like one with unusual coercion rules. Two of those rules produce most of the surprises: any non-empty string is truthy, and an unavailable context is an empty string rather than an error.
Together they mean a condition can be permanently true or permanently false with nothing in the log to indicate why.
Operators
| Operator | Meaning | Note |
|---|---|---|
== / != | Equality | Loose: types are coerced before comparison |
< <= > >= | Ordering | Numeric comparison |
&& || | And / or | Return the operand, not a boolean |
! | Not | |
( ) | Grouping | |
. and [ ] | Property access | [ ] needed for keys with dashes |
* | Wildcard in filter patterns | Only in path and branch filters |
Status check functions
| Function | True when |
|---|---|
success() | No previous step or job has failed. The implicit default |
failure() | A previous step or job has failed |
cancelled() | The workflow was cancelled |
always() | Always, including on cancellation |
The truthiness rule that breaks conditions
# a step output is ALWAYS a string, so this is true even when it is "false"
- if: ${{ steps.check.outputs.should_run }}
# compare to the string explicitly
- if: ${{ steps.check.outputs.should_run == 'true' }}
# and remember an unavailable context is an empty string,
# so this is false rather than an error:
- if: ${{ steps.missing.outputs.value == 'true' }}Useful functions
| Function | Use |
|---|---|
contains(haystack, needle) | Substring or array membership |
startsWith / endsWith | String prefix and suffix |
format(str, ...) | Interpolation with {0} placeholders |
join(array, sep) | Flatten an array to a string |
toJSON(value) | Serialise, invaluable for debugging |
fromJSON(str) | Parse, used for dynamic matrices |
hashFiles(path) | Content hash, used for cache keys |
Dynamic matrices with fromJSON
jobs:
discover:
runs-on: ubuntu-latest
outputs:
targets: ${{ steps.set.outputs.targets }}
steps:
- id: set
run: echo 'targets=["a","b","c"]' >> "$GITHUB_OUTPUT"
build:
needs: discover
strategy:
matrix:
target: ${{ fromJSON(needs.discover.outputs.targets) }}
runs-on: ubuntu-latestDiagnose it: print the context before you change anything
Most workflow-expression bugs are not syntax errors, they are an expression reading something that is empty. GitHub resolves a missing property to an empty string instead of failing the run, so a wrong reference looks like a logic bug rather than a mistake. Dump the contexts first and you will usually see the answer immediately.
- name: Dump contexts
run: |
echo '--- github ---' ; echo '${{ toJSON(github) }}'
echo '--- needs ---' ; echo '${{ toJSON(needs) }}'
echo '--- steps ---' ; echo '${{ toJSON(steps) }}'
echo '--- matrix ---' ; echo '${{ toJSON(matrix) }}'
echo '--- inputs ---' ; echo '${{ toJSON(inputs) }}'Check the context is allowed where you used it
Contexts are not available everywhere. The same expression can be valid in a step if and invalid in a job if, which is why an expression that works in one workflow fails when moved.
| Where you wrote it | Contexts available there |
|---|---|
run-name | github, inputs, vars |
concurrency | github, inputs, vars |
Top-level env | github, secrets, inputs, vars |
jobs.<id>.if | github, needs, vars, inputs |
jobs.<id>.steps.if | github, needs, strategy, matrix, job, runner, env, vars, steps, inputs |
jobs.<id>.outputs | Full access, including secrets |
Reusable workflow outputs | github, jobs, vars, inputs |
Catch it before it reaches CI
Every failure in this cluster is statically detectable. actionlint parses workflow expressions, checks context availability against the same rules above, and validates needs references, so these bugs never need to cost you a run.
# one-off
docker run --rm -v "$(pwd):/repo" --workdir /repo rhysd/actionlint:latest -color
# as a job, before anything expensive runs
- uses: actions/checkout@v4
- run: |
bash <(curl -s https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash)
./actionlint -colorFrequently asked questions
Why does my GitHub Actions if condition always run?
"false". Compare explicitly: if: steps.x.outputs.flag == 'true'.What is the difference between always() and !cancelled()?
always() runs even when the workflow is cancelled, which makes cancellation ineffective for that step. !cancelled() runs after success or failure but still respects a cancellation, which is usually what cleanup steps want.Why is my fromJSON matrix empty?
How do I set a default value in an expression?
||, which returns its operand rather than a boolean: ${{ inputs.name || 'default' }} yields default when inputs.name is empty.