Welcome to the thrilling world of environment variables in GitHub Actions. Think of them as sticky notes for your CI process. When used well they keep workflows readable and secure. When used poorly they leak secrets into logs and ruin your morning.

Basics and scope

Environment variables are key value pairs available to your workflow at different scopes. You can define them at workflow level to apply to everything, at job level to limit exposure to one job, or at step level for one tiny operation that nobody else needs to see. When names collide the narrower scope wins with step level overriding job level and job level overriding workflow level.

Set a variable during a run

If you need to create a variable at runtime write to the special file that the runner watches. That value will be available to later steps in the same job. Example shell usage:

echo "MY_VAR=hello" >> $GITHUB_ENV

Later you can read it with the env context like this

echo Hello $

Secrets are a different beast

Sensitive data should live in the secrets context. Use the secrets object for tokens and keys. Example:

echo $

Secrets are masked in logs so you avoid accidental public confessions. Do not deliberately echo them unless you enjoy rewriting history.

Passing values between jobs

Steps can set outputs that jobs can consume. If you need to move data between completely separate jobs consider job outputs or artifacts. Both require a few extra lines but they save you from brittle hacks.

Quick options

• Use job outputs for structured data that the next job will consume
• Upload artifacts when the data is large or binary
• Prefer secrets for anything sensitive and avoid putting secrets in $GITHUB_ENV

Common pitfalls and best practices

• Do not print secrets to logs. Masking helps but human error is dramatic and fun for villains
• Assume step level env changes do not cross job boundaries unless explicitly exported
• Use uppercase names with underscores for clarity and to avoid clashing with runner variables
• Keep scopes narrow. The smaller the blast radius the less you will cry later

Final words of grudging wisdom

Prefer storing sensitive values in the secrets context and use $GITHUB_ENV for dynamic runtime values. Name variables clearly and scope them as tightly as possible. Follow these rules and your CI will be tidy and mostly boring. Break them and you will enjoy debugging in production at three in the morning.