Environment Variables, Configuration Variables, Outputs, and Data Passing: Diagnostics, Failure Modes, and Production Practices

1. Evidence-first diagnostic sequence

1. Preserve the run ID, attempt, exact workflow/source SHA, job/step names, and first failing/missing-value logs.
2. Name the value and its intended producer and consumer.
3. Locate its mechanism: YAML env, vars, default environment, GITHUB_ENV, step output, job output, or file/artifact.
4. Check lifecycle/scope: same step, later step same job, downstream job, or later workflow.
5. Check naming/precedence and exact output IDs.
6. Check framing/encoding/size and whether the payload is sensitive or arbitrary.
7. Apply one causal correction and rerun the smallest equivalent scope.

2. Failure: expecting GITHUB_ENV to cross jobs

jobs:
  produce:
    runs-on: ubuntu-24.04
    steps:
      - run: echo 'BUILD_LABEL=demo-17' >> "$GITHUB_ENV"
  consume:
    needs: produce
    runs-on: ubuntu-24.04
    steps:
      - run: test "$BUILD_LABEL" = 'demo-17'

The consumer fails because the producer's environment-file update belongs only to later steps in produce. The needs edge orders jobs but does not share a process environment or filesystem.

Causal repair: publish BUILD_LABEL through GITHUB_OUTPUT, map it to a job output, and consume needs.produce.outputs.build_label. Do not add a self-hosted runner or shared disk to “fix” a missing interface.

3. Failure: trying to overwrite authoritative default variables

- name: Wrong mental model
  run: |
    echo 'GITHUB_SHA=fake-value' >> "$GITHUB_ENV"
    echo 'RUNNER_OS=fake-os' >> "$GITHUB_ENV"

Current GitHub documentation says default GITHUB_* and RUNNER_* values cannot be overwritten this way. If you need a synthetic comparison value, give it an application-owned name such as EXPECTED_SHA. Never shadow evidence fields to make logs look convenient.

4. Failure: copying the deprecated stdout set-output pattern

# Historical pattern — do not use in new workflow code:
echo "::set-output name=version::1.2.3"

GitHub introduced environment files to reduce risks around workflow commands emitted through stdout. Current guidance is:

echo 'version=1.2.3' >> "$GITHUB_OUTPUT"

When reviewing old tutorials, distinguish “still observed in legacy workflows” from “recommended current design.” New course code uses GITHUB_OUTPUT.

5. Failure: delimiter collision corrupts multiline framing

This intentionally broken synthetic example chooses a delimiter that appears in the payload:

{
  echo 'NOTE<> "$GITHUB_ENV"

The framing ends too early. If the payload is fully controlled, generate a collision-resistant delimiter. If the payload is arbitrary, current guidance is to write it to a file rather than betting on a delimiter that “probably” will not occur.

6. Failure: using outputs as a large/binary transport

Encoding a multi-megabyte report or binary into a step/job output creates unnecessary size, quoting, and integrity problems and may exceed output limits. Preserve the generated file, compute a digest if needed, transfer the file via artifact/file mechanism, and keep only the digest/name/version as a small output.

7. Failure: naming collision hides origin

env:
  REGION: workflow-demo
jobs:
  test:
    env:
      REGION: job-demo
    steps:
      - env:
          REGION: step-demo
        run: echo "$REGION"

The shell prints step-demo, but a reviewer may wrongly attribute it to repository configuration or workflow-level state. Fix the architecture by removing unnecessary collisions or naming layers explicitly. Do not diagnose precedence by printing entire contexts that may include sensitive values.

8. Failure: echoing sensitive data because “masking will handle it”

Configuration variables are unmasked, and secret masking is not a substitute for correct data handling. Never print a token, secret, private key, OIDC token, or derived credential merely to confirm transport. Prove the interface with synthetic stand-ins and use bounded metadata such as “credential present” only when safe and necessary.

9. Causal diagnosis matrix

10. Intentionally broken mini-lab

In a disposable repository, run the cross-job GITHUB_ENV defect above and preserve the failed run. Then change only the producer/consumer interface to a job output. Keep trigger, runner, permissions, source data, and expected value identical. The repaired run proves causality because the transport mechanism is the only material change.

Record both run IDs/attempts, workflow SHAs, producer step conclusion, consumer failure/success, and the exact output name. Do not erase the original failed evidence.

11. Production practice: dataflow contracts are observable interfaces

Production workflow reviews should treat outputs and configuration like APIs: names are stable, producers and consumers are explicit, sensitivity is classified, sizes are bounded, and change history is reviewable. When a value disappears, debug the contract before changing runners, permissions, or external infrastructure.

Knowledge check

Official references and version notes

• Variables — current distinction between workflow env, configuration variables, default variables, and secrets.
• Variables reference — current default variables, naming rules, precedence, configuration-variable limits, and context guidance.
• Store information in variables — current examples for workflow/job/step environment variables, configuration variables, contexts, and cross-step/job data flow.
• Workflow commands for GitHub Actions — current environment files including GITHUB_ENV, GITHUB_OUTPUT, multiline syntax, and restrictions.
• Passing information between jobs — current job-output mapping and needs.<job>.outputs consumption.
• Workflow syntax for GitHub Actions — current env, job outputs, needs, output size limits, and workflow syntax.
• Store and share data with workflow artifacts — current artifact model for files that must outlive a step/job filesystem or are inappropriate for small outputs.
• GitHub Actions changelog: set-output update — why new workflow code should use environment files rather than the deprecated stdout set-output command.