Environment Variables

Environment variables in GitHub Actions let you pass configuration, secrets, and runtime values into your workflows. This guide explains where to define environment variables, how scoping and precedence work, common pitfalls (especially with CI tests), and best practices for secrets. This article covers:

Job-level environment variables (scoped to a single job)
Workflow-level environment variables (shared across jobs)
Step-level environment variables (scoped to a specific step)
Common runtime errors caused by missing env vars
Best practices for secrets and CI databases

Scopes and precedence

GitHub Actions supports env at three levels:

Workflow-level: declared at the top level, available to every job and step unless overridden.
Job-level: declared inside a job; available only to steps in that job.
Step-level: declared inside a step; overrides job/workflow variables with the same name.

Precedence: step-level > job-level > workflow-level.

Step-level env entries override job-level and workflow-level variables with the same name. Use step-level for single-step overrides and job-level for values shared by multiple steps in the same job.

Job-level environment variables

Define job-level variables under jobs.<job_id>.env. These values are available to all steps in that job only. Example: a job-level env for tests and build steps.

name: Build and Deploy Code

on: [push, pull_request]

jobs:
  job1:
    runs-on: ubuntu-latest
    env:
      DATABASE_HOSTNAME: localhost
      DATABASE_PORT: 5432
      DATABASE_PASSWORD: password123
      DATABASE_NAME: fastapi
      DATABASE_USERNAME: postgres
      SECRET_KEY: 09d25e094faa6ca2556c818166b7a9563b93f7099f6f0f4caa6cf63b88e8d3e7
      ALGORITHM: HS256
      ACCESS_TOKEN_EXPIRE_MINUTES: 30
    steps:
      - name: Pull repository
        uses: actions/checkout@v2
      - name: Set up Python 3.9
        uses: actions/setup-python@v2
        with:
          python-version: "3.9"
      - name: Update pip
        run: python -m pip install --upgrade pip
      - name: Install dependencies
        run: pip install -r requirements.txt
      - name: Run tests
        run: |
          pip install pytest
          pytest

Because these variables are under job1.env, they are not visible to other jobs (e.g., job2) unless you duplicate or lift them to workflow-level.

Why missing env vars cause runtime errors

If your application reads required configuration from environment variables (for example, a Pydantic Settings class), missing values can cause immediate initialization failures. Typical CI error output from Pydantic looks like this:

E   pydantic.error_wrappers.ValidationError: 8 validation errors for Settings
E   database_hostname
E     field required (type=value_error.missing)
E   database_port
E     field required (type=value_error.missing)
E   ...
[Error]: Process completed with exit code 4.

This indicates the runner could not find the expected env vars when importing your application code. To avoid this, ensure required env vars are provided by the workflow (or mocked/stubbed during tests).

Step-level environment variables

Use env inside a specific step to provide values only that step needs. Step-level vars override those at job or workflow scope when names collide. Example: job-level env with a conditional step that uses step-level overrides. Note the GitHub Actions expression is shown in the YAML:

jobs:
  weekday_job:
    runs-on: ubuntu-latest
    env:
      DAY_OF_WEEK: Mon
    steps:
      - name: "Hello world when it's Monday"
        if: ${{ env.DAY_OF_WEEK == 'Mon' }}
        run: echo "Hello $FIRST_NAME $middle_name $Last_Name, today is Monday!"
        env:
          FIRST_NAME: Mona
          middle_name: The
          Last_Name: Octocat

Built-in environment variables

Runners expose many built-in environment variables such as GITHUB_REPOSITORY, GITHUB_RUN_NUMBER, and GITHUB_SHA. Use these when you need metadata about the current workflow run. See the GitHub Docs for the full list:

Environment variables - GitHub Actions

A screenshot of the GitHub Docs website showing a reference table of GitHub Actions environment variables and their descriptions. The page includes a left navigation menu and browser tabs visible across the top.

Workflow-level environment variables (shared across jobs)

If many jobs require the same variables, define them at the workflow root (one level above jobs). These variables propagate to all jobs and steps unless overridden. Example:

name: Build and Deploy Code

on: [push, pull_request]

env:
  DATABASE_HOSTNAME: localhost
  DATABASE_PORT: 5432
  DATABASE_PASSWORD: password123
  DATABASE_NAME: fastapi
  DATABASE_USERNAME: postgres
  SECRET_KEY: 09d25e094faa6ca2556c818166b7a9563b93f7099f6f0f4caa6cf63b88e8d3e7
  ALGORITHM: HS256
  ACCESS_TOKEN_EXPIRE_MINUTES: 30

jobs:
  job1:
    runs-on: ubuntu-latest
    steps:
      - name: Pull repository
        uses: actions/checkout@v2
      - name: Set up Python 3.9
        uses: actions/setup-python@v2
        with:
          python-version: "3.9"
      - name: Run tests
        run: |
          pip install pytest
          pytest

  job2:
    runs-on: ubuntu-latest
    steps:
      - name: Another step
        run: echo "job2 can access the workflow-level environment variables"

Common workflow mistakes

Leaving a job with no steps will cause the workflow parser to reject the file. Example error:

Invalid workflow file: .github/workflows/build-deploy.yml#L1
No 'steps' defined in 'steps' for the following jobs: job2

Expecting job1.env to be available in job2—job-level variables are not shared.

Runner logs and environment validation

When a runner executes a step, it often prints an environment dump that shows the env variables available to that step. This is helpful for debugging and confirming that variables are set. For example:

Run pip install pytest
pip install pytest
pytest
shell: /usr/bin/bash -e {0}
env:
DATABASE_HOSTNAME: localhost
DATABASE_PORT: 5432
DATABASE_PASSWORD: password123
DATABASE_NAME: fastapi
DATABASE_USERNAME: postgres
SECRET_KEY: 09d25e094faa6ca2556c818166b7a9563b93f7099f6f0f4caa6cf63b88e8d3e7
ALGORITHM: HS256
ACCESS_TOKEN_EXPIRE_MINUTES: 30
pythonLocation: /opt/hostedtoolcache/Python/3.9.7/x64
LD_LIBRARY_PATH: /opt/hostedtoolcache/Python/3.9.7/x64/lib
Collecting pytest
...

Note: GitHub Actions automatically masks secrets in logs. If you use GitHub Secrets, their values will be redacted and not shown in plain text.

Note about testing databases in CI

If your tests rely on a database at localhost, you must either start a database service on the runner or connect to an external test database. GitHub Actions supports service containers (for example, the official postgres service) to spin up databases during the job:

Use the GitHub Actions service containers feature: https://docs.github.com/en/actions/using-jobs/using-service-containers/about-service-containers

If the runner lacks a database, DB libraries (e.g., SQLAlchemy) will raise connection errors during setup:

________________ ERROR at setup of test_get_all_posts ________________

self = Engine('***localhost:5432/fastapi_test')
...
    def connect(self):
        """Return a DBAPI connection from the pool."""
        return _ConnectionFairy._checkout(self)

Best practices for secrets

Never hard-code sensitive values (production credentials, private keys, tokens) in your repository or workflow YAML. Instead, store them in GitHub Secrets and reference them via the secrets context. Example:

env:
  DATABASE_PASSWORD: ${{ secrets.DB_PASSWORD }}

Never store sensitive credentials in plaintext in your repository. Use GitHub Secrets (or another secrets manager) and reference them via the secrets context so the values are kept private and not visible in your repo.

Quick reference table

Scope	Visibility	Typical use
Workflow-level `env`	All jobs and steps (unless overridden)	Global configuration shared across jobs
Job-level `env`	All steps in the job	Values required only by that job
Step-level `env`	That step only (overrides others)	Temporary overrides or step-specific secrets

Summary

Use workflow-level env for values shared across jobs.
Use job-level env for values used by multiple steps within the same job.
Use step-level env for single-step values and to override broader scopes.
Always use secrets for sensitive data and never commit credentials to the repo.
Ensure CI services (like databases) are available to the runner when tests expect them.

Introduction

Python Setup

FastAPI Basics

Working with Databases

Databases with Python

Advanced FastAPI

Database Migration

Deployment

Testing

CI/CD

Environment Variables

Scopes and precedence

Job-level environment variables

Why missing env vars cause runtime errors

Step-level environment variables

Built-in environment variables

Workflow-level environment variables (shared across jobs)

Common workflow mistakes

Runner logs and environment validation

Note about testing databases in CI

Best practices for secrets

Quick reference table

Summary

Links and references

Watch Video

​Scopes and precedence

​Job-level environment variables

​Why missing env vars cause runtime errors

​Step-level environment variables

​Built-in environment variables

​Workflow-level environment variables (shared across jobs)

​Common workflow mistakes

​Runner logs and environment validation

​Note about testing databases in CI

​Best practices for secrets

​Quick reference table

​Summary

​Links and references

Watch Video

Scopes and precedence

Job-level environment variables

Why missing env vars cause runtime errors

Step-level environment variables

Built-in environment variables

Workflow-level environment variables (shared across jobs)

Common workflow mistakes

Runner logs and environment validation

Note about testing databases in CI

Best practices for secrets

Quick reference table

Summary

Links and references