Contexts, Expressions, Functions, Conditionals, and Evaluation Semantics: Configuration, Design Patterns, and Trade-Offs

1. The design question: who should evaluate this decision?

A condition can be evaluated by GitHub before runner allocation, by the Actions runner while preparing a step, or by the shell/program inside the step. Each location has different context availability and trust implications. Put the decision at the earliest layer that has all required trusted data—but not earlier.

2. Expression interpolation versus shell interpolation

GitHub expressions are evaluated before a run script is handed to the shell. If attacker-controlled text is embedded directly into that script, the text can change the script itself.

# WRONG for untrusted PR titles
- name: Unsafe title check
  run: |
    title="${{ github.event.pull_request.title }}"
    printf '%s\n' "$title"

The shell never receives an abstract “value”; it receives a generated script after GitHub substitutes the expression. A malicious title containing shell syntax can therefore alter the script.

# SAFER boundary
- name: Safe title check
  env:
    PR_TITLE: ${{ github.event.pull_request.title }}
  run: |
    printf '%s\n' "$PR_TITLE"

The value is data in the environment and is quoted when the shell expands it. Even better, a dedicated action/program can receive untrusted text as an argument and avoid shell parsing entirely.

3. Job-level versus step-level if

A common anti-pattern is admitting an expensive job and then skipping every step because a decision that could have been made before runner allocation was placed too late.

4. Typed inputs versus string assumptions

For a manually triggered workflow, define the contract in workflow_dispatch.inputs. The inputs context preserves supported types such as Boolean and number. Prefer this:

if: ${{ inputs.deploy_preview && inputs.replicas >= 2 }}

over reconstructing a Boolean contract from event strings:

# Fragile and needlessly string-oriented
if: ${{ github.event.inputs.deploy_preview == 'true' }}

The second version can be necessary when interoperating with a string-only source, but it should be a deliberate adapter, not the default mental model.

5. Loose equality is a compatibility feature, not a design strategy

GitHub ignores case when comparing strings and performs loose equality. Type mismatches can trigger numeric coercion. That can produce surprising matches: an empty string and numeric zero can participate in the same numeric comparison path. Non-numeric strings can become NaN, making relational comparisons false.

6. Missing data and null-like meaning are not the same thing

A nonexistent context property evaluates to an empty string. That is convenient for optional payload fields but dangerous if an empty string is also a valid business value. Make “missing” a documented state when it matters.

- name: Explain optional field
  env:
    LABEL: ${{ github.event.pull_request.head.label }}
    OPTIONAL_FIELD: ${{ github.event.client_payload.optional_field }}
  run: |
    if [[ -z "$OPTIONAL_FIELD" ]]; then
      echo 'optional field is absent or empty; business contract must distinguish if needed'
    fi

Do not silently interpret every empty string as false, zero, or “not applicable.” Decide what the integration contract means.

7. Early expression evaluation versus runtime environment expansion

Default environment variables such as GITHUB_REF exist on the runner. They are not entries in the workflow-defined env context. For a job-level condition, use the corresponding github.ref context. Inside a shell step, use the runner environment variable normally.

jobs:
  main-only:
    if: ${{ github.ref == 'refs/heads/main' }}
    runs-on: ubuntu-24.04
    steps:
      - run: printf 'runtime GITHUB_REF=%s\n' "$GITHUB_REF"

This is not duplicate data by accident; it reflects two lifecycle surfaces.

8. Selection logic: prefer explicit current functions over clever chains

Current expression reference includes case(), which can make multi-branch selection clearer than deeply nested Boolean chains. If you use the older condition && valueA || valueB idiom, remember that a falsy valueA can cause the fallback branch to win unexpectedly.

env:
  TARGET_TIER: ${{ case(
    github.ref == 'refs/heads/main', 'production',
    startsWith(github.ref, 'refs/heads/release/'), 'staging',
    'development'
  ) }}

Because GitHub is continuously delivered, treat newer expression functions as version-sensitive and re-check current platform support before depending on them in long-lived templates.

9. Decision table for maintainable conditions

10. Review checklist before merging a condition

• Every referenced context is available at this exact workflow key.
• Every value's type is known or explicitly converted.
• No condition depends on accidental loose coercion.
• Untrusted event text never becomes generated shell source.
• Sensitive contexts are not logged for convenience.
• Status behavior is explicit after failures.
• Job-level decisions are used when they can avoid unnecessary runner work.
• Runtime-only state is not referenced before it exists.
• Failure/skip evidence remains distinguishable from a run that never existed.

Knowledge check

Official references and version notes

• Evaluate expressions in workflows and actions — current literals, truthiness, loose equality/coercion, built-in functions, fromJSON/toJSON, and status-check functions.
• Contexts reference — current context objects, missing-property behavior, per-key context availability, and steps/runner/inputs semantics.
• Workflow syntax for GitHub Actions — current if, workflow_dispatch input types, environment scopes, job/step syntax, and permission placement.
• Script injections — why attacker-controlled context text must not be substituted directly into generated shell scripts.
• Secure use reference — current safe handling guidance for secrets, untrusted context values, permissions, and workflow code.
• Variables reference — distinction between default runner environment variables and expression contexts.