GitHub Actions env context not available in jobs.<id>.if

By Daniel Zoghalchali·Latchkey

The env context is available in most step keys but NOT in jobs.<id>.if, jobs.<id>.name, or runs-on at job scope. Referencing env there evaluates to empty and the condition behaves unexpectedly.

What this error means

A job-level if that reads env.* never matches, or the workflow errors that env is not a recognized named-value in that location.

Unrecognized named-value: 'env'. Located at position 1 within expression: env.DEPLOY == 'true'

Common causes

env referenced in job-level if

jobs.<id>.if is evaluated before job env is available, so env.* is not in scope.

env used in runs-on or job name

These keys also lack the env context at job scope.

How to fix it

Use a context that is in scope

1. Gate job-level if on github.*, inputs.*, or needs.*.outputs.* instead of env.*.
2. Move env-based conditions into step-level if, where env is available.
3. Or compute a value in an upstream job output and branch on needs.<job>.outputs.*.

jobs:
  deploy:
    if: ${{ github.ref == 'refs/heads/main' }}
    runs-on: ubuntu-latest
    steps:
      - if: env.DEPLOY == 'true'   # env IS available at step scope
        run: ./deploy.sh

How to prevent it

• Reserve env.* conditions for step-level if.
• For job gating, use github, inputs, or needs outputs.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions