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

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.

github-actions

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

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

.github/workflows/deploy.yml

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.