GitHub Actions if condition always runs (string vs expression)

By Kaveh Alemi·Latchkey

GitHub Actions treats a non-empty if value as a truthy string unless it is a real expression. Writing if: github.ref == 'refs/heads/main' without \${{ }} can still evaluate, but a malformed or quoted condition silently becomes "always run".

What this error means

A step or job that should be conditional runs on every event. There is no error; the condition is just always true because it is parsed as a constant string.

# This ALWAYS runs - the whole thing is a literal string, not evaluated
if: "github.event_name == 'push' && success()"

Diagnose 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.

Common causes

Condition wrapped so it reads as a literal

Quoting the entire condition or omitting expression syntax can turn it into a constant truthy string.

Non-empty string is truthy

Any non-empty if value that is not a false expression evaluates as true.

How to fix it

Write a proper expression condition

1. Use the bare expression form: if: github.event_name == 'push'.
2. Or wrap explicitly: if: \${{ github.event_name == 'push' && success() }}.
3. Do not quote the whole condition string.

steps:
  - name: Deploy
    if: ${{ github.ref == 'refs/heads/main' && success() }}
    run: ./deploy.sh

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 -color

How to prevent it

• Prefer the \${{ }} form for non-trivial conditions to make intent explicit.
• Test conditions on a branch and confirm the step skips when expected.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions