Contexts, Expressions, Functions, Conditionals, and Evaluation Semantics: Core Concepts and Mental Model

1. The practical problem: “Why did this condition run?”

Trigger design tells you why a workflow run exists. Expression design tells you why the run took one path instead of another. A production incident often sounds like “the deploy job unexpectedly ran,” “the cleanup step never executed after failure,” or “the boolean input was false but the condition was true.” Those are not generic YAML problems. They are dataflow problems.

To diagnose them, preserve four facts: the expression source, the contexts available at that workflow key, the runtime value and type, and the status state that GitHub implicitly or explicitly adds. Without those facts, changing punctuation until the workflow turns green is guesswork.

2. Mental model: state becomes contexts; contexts become decisions

flowchart TD
  A[Event + workflow metadata] --> B[Early contexts: github inputs vars needs]
  B --> C[Expression evaluation]
  C --> D[Job admitted or skipped]
  D --> E[Runner assigned]
  E --> F[Runtime contexts: runner job steps env]
  F --> G[Step expressions + shell environment]
  G --> H[Outputs conclusions evidence]

The important boundary is between GitHub-side evaluation and runner-side execution. A job-level if can be evaluated before any runner is assigned, so it cannot depend on runner-only state such as runner.os. A step-level condition runs later, when the job and previous step records exist. The same expression syntax therefore does not imply the same data is available everywhere.

3. Contexts are typed objects with scope, not global dictionaries

The authoritative context-availability table in GitHub documentation is part of your production contract. When a context is not listed for a workflow key, changing quotation marks will not make it available.

4. Expressions have types, truthiness, and coercion

GitHub expressions support Boolean, null, number, and string literals. In a conditional, documented falsy values—false, numeric zero, empty string, and null—become false; other values are truthy. This is why the non-empty string 'false' is dangerous when someone assumes it behaves like the Boolean false.

Equality is intentionally loose. If operand types differ, GitHub may coerce them to numbers. For example, null becomes 0, Boolean true becomes 1, empty string becomes 0, and a non-numeric string can become NaN. Relational comparisons involving NaN are false. A workflow that depends on accidental coercion is difficult to review; normalize types explicitly instead.

5. Expression syntax and shell syntax are two different languages

${{ ... }} asks GitHub to evaluate an expression. A shell variable such as $NAME or ${NAME} is expanded later by the shell running on the assigned runner. Mixing the two phases can create both correctness and security bugs.

jobs:
  explain:
    if: ${{ github.ref == 'refs/heads/main' }}   # GitHub evaluates this first
    runs-on: ubuntu-24.04
    steps:
      - name: Runtime expansion
        env:
          SAFE_REF: ${{ github.ref }}             # GitHub copies data into env
        run: |
          printf 'ref=%s\n' "$SAFE_REF"           # Bash expands quoted env value

In an if condition the outer ${{ }} delimiters are usually optional. Elsewhere, use them where the workflow syntax expects an expression. Keep expression literals and shell quoting rules mentally separate.

6. Functions transform data; they do not erase type questions

Useful built-ins include contains, startsWith, endsWith, format, join, toJSON, fromJSON, hashFiles, and current case selection syntax. Availability can depend on the workflow key; for example, hashFiles operates on files in GITHUB_WORKSPACE and is not a universal pre-run function.

env:
  MODE: ${{ case(inputs.verbose, 'verbose', 'normal') }}
  SAFE_LIST: ${{ join(fromJSON('["lint","test"]'), ',') }}

Do not use toJSON as permission to dump entire contexts. It is a serialization function, not a redaction boundary. Serialize only synthetic or explicitly allow-listed values.

7. Every conditional also has a status dimension

For if expressions, GitHub applies a default status check of success() unless your condition includes a status-check function. That means a step after a failure may not run even if its business expression is true.

8. Read-only inspection: allow-list context fields

name: Chapter 04 context probe
on:
  workflow_dispatch:
    inputs:
      enabled:
        description: 'Enable the probe'
        type: boolean
        required: true
        default: true
permissions: {}
jobs:
  inspect:
    if: ${{ inputs.enabled }}
    runs-on: ubuntu-24.04
    steps:
      - name: Bounded context evidence
        env:
          EVENT: ${{ github.event_name }}
          REF: ${{ github.ref }}
          SHA: ${{ github.sha }}
          WORKFLOW_SHA: ${{ github.workflow_sha }}
          RUNNER_OS: ${{ runner.os }}
          RUNNER_ARCH: ${{ runner.arch }}
        run: |
          printf 'event=%s ref=%s sha=%s workflow_sha=%s\n' "$EVENT" "$REF" "$SHA" "$WORKFLOW_SHA"
          printf 'runner_os=%s runner_arch=%s run=%s attempt=%s\n' \
            "$RUNNER_OS" "$RUNNER_ARCH" "$GITHUB_RUN_ID" "$GITHUB_RUN_ATTEMPT"

This is enough to prove event/workflow/runner identity without printing the whole github, secrets, or event payload objects.

9. Production rule: make conditions reviewable as dataflow

A reviewer should be able to read a condition and answer: where did every value come from, what type does it have, at which lifecycle phase is it available, is any field attacker-controlled or sensitive, what status function is implicit/explicit, and what observable state changes if the condition is true? If those questions cannot be answered, the condition is too magical.

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.