Contexts, Expressions, Functions, Conditionals, and Evaluation Semantics: Diagnostics, Failure Modes, and Production Practices

1. Evidence-first diagnostic sequence

1. Preserve the run ID/attempt and first failing/skipped job/step evidence.
2. Confirm event/ref/SHA and exact workflow revision (github.workflow_sha / repository commit).
3. Copy the exact expression text before editing it.
4. Identify the workflow key: job if, step if, env, with, run, etc.
5. Check the authoritative context-availability table for that key.
6. Record the real source type: Boolean, number, string, missing/empty, step-output string, untrusted event text, or secret.
7. Account for implicit success() or explicit status functions.
8. Separate GitHub expression substitution from runner shell expansion.
9. Apply the smallest correction, rerun the smallest equivalent scope, and compare evidence.

Do not “fix” expression failures by granting wider tokens, changing runners, deleting run history, or replacing the event. Those changes alter unrelated layers and destroy causal clarity.

2. Failure A — untrusted context becomes shell source

# Intentionally unsafe teaching example — do not keep
- name: Check PR title
  run: |
    title="${{ github.event.pull_request.title }}"
    if [[ "$title" == docs:* ]]; then
      echo 'docs PR'
    fi

A malicious title can contain shell syntax. GitHub substitutes the expression before Bash parses the temporary script, so the attacker can alter the script structure. This is not solved by adding more nested quotes around the expression.

- name: Check PR title safely
  env:
    PR_TITLE: ${{ github.event.pull_request.title }}
  run: |
    if [[ "$PR_TITLE" == docs:* ]]; then
      echo 'docs PR'
    fi

For more complex parsing, pass the title to a dedicated program/action argument. Treat branch names, PR titles/bodies, issue text, labels, emails, and other user-controlled event fields as untrusted data.

3. Failure B — Boolean input reconstructed as a string

on:
  workflow_dispatch:
    inputs:
      enabled:
        type: boolean
        required: true
        default: false
jobs:
  broken:
    if: ${{ github.event.inputs.enabled == true }}
    runs-on: ubuntu-24.04
    steps:
      - run: echo 'expected to run when enabled=true'

The event-input representation is a string while true is a Boolean. Loose comparison invokes numeric coercion; the string 'true' is not a legal JSON number and becomes NaN, so the equality does not represent the intended Boolean contract.

jobs:
  fixed:
    if: ${{ inputs.enabled }}
    runs-on: ubuntu-24.04
    steps:
      - run: echo 'typed Boolean contract'

An even worse variant is if: github.event.inputs.enabled: both string 'true' and string 'false' are non-empty and therefore truthy.

4. Failure C — the diagnostic condition forgets implicit success()

steps:
  - name: Deliberate failure
    id: test
    run: exit 2

  - name: Broken failure diagnosis
    if: ${{ steps.test.conclusion == 'failure' }}
    run: echo 'this may be suppressed by the default status gate'

Because the condition contains no status-check function, GitHub applies the default success() check. After a failing previous step, the effective condition is not simply “conclusion equals failure.”

  - name: Correct failure diagnosis
    if: ${{ failure() && steps.test.conclusion == 'failure' }}
    run: echo 'preserve and explain the original failure'

Do not change the failing step to continue-on-error: true just to make the diagnostic execute. That changes failure policy rather than fixing the condition.

5. Failure D — context referenced before it exists

jobs:
  broken:
    if: ${{ runner.os == 'Linux' }}
    runs-on: ubuntu-24.04
    steps:
      - run: echo 'Linux-only behavior'

The job condition is evaluated before runner assignment; runner is not an allowed job-level if context. The correct design depends on intent:

• If the runner is statically ubuntu-24.04, the condition is redundant—remove it.
• If a later matrix/runner choice makes OS dynamic, use the allowed pre-run configuration data or evaluate runner.os at step scope after assignment.

6. Failure E — context dumping creates a disclosure boundary problem

# Do not use as a generic debugging pattern
- env:
    EVERYTHING: ${{ toJSON(github) }}
  run: printf '%s\n' "$EVERYTHING"

The github context can include sensitive values such as github.token, and event subfields can contain attacker-controlled content. Masking is not a reason to intentionally log it. Build an allow-list:

- env:
    EVENT: ${{ github.event_name }}
    REF: ${{ github.ref }}
    SHA: ${{ github.sha }}
    WORKFLOW_SHA: ${{ github.workflow_sha }}
  run: printf 'event=%s ref=%s sha=%s workflow_sha=%s\n' "$EVENT" "$REF" "$SHA" "$WORKFLOW_SHA"

7. Failure F — expression quoting and shell quoting are confused

Inside ${{ }}, string literals use GitHub expression rules. Inside Bash, quoting follows Bash rules. The following patterns solve different problems:

Adding shell escaping characters inside a GitHub expression can make the expression invalid; adding expression quotes around a shell variable does nothing because the shell runs later.

8. Controlled broken workflow

In a disposable repository, commit a workflow containing only the Boolean/string failure and implicit-success failure. Do not include the script-injection example in a privileged/untrusted workflow; it is shown above for analysis and should remain inert course text.

name: Chapter 04 diagnostic lab
on:
  workflow_dispatch:
    inputs:
      enabled:
        type: boolean
        required: true
        default: true
permissions: {}
jobs:
  wrong-type:
    if: ${{ github.event.inputs.enabled == true }}
    runs-on: ubuntu-24.04
    steps:
      - run: echo 'unexpectedly skipped due to string/Boolean mismatch'

  status-demo:
    runs-on: ubuntu-24.04
    steps:
      - id: test
        run: exit 2
      - name: Broken diagnostic
        if: ${{ steps.test.conclusion == 'failure' }}
        run: echo 'does not override implicit success'

Capture the first run. Then create a second workflow revision replacing the job condition with inputs.enabled and the step condition with failure() && steps.test.conclusion == 'failure'. Compare run IDs, workflow SHAs, skipped/executed states, and final job conclusions.

9. Production practices

• Treat context-availability tables as API contracts.
• Keep typed values typed; convert strings once at well-defined boundaries.
• Assume event/user text is untrusted until safely passed as data.
• Never print secrets or whole broad contexts to diagnose a condition.
• Use status functions deliberately after failures and cancellation.
• Preserve the original failing run before rerunning; a rerun is new evidence, not a replacement.
• Do not broaden token permissions, switch to privileged triggers, or use trusted self-hosted runners to “fix” expression logic.

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.