Environment Variables

Environment variable definitions and precedence rules at three levels — Workflow, Job, and Step

Environment variables (env) can be defined at three levels: Workflow, Job, and Step. If the same key is declared at a lower level, it overrides the value from the upper level.

For how to register secrets and variables, see the Secrets and Variables guide.

Below is an example of the variable management UI.

Override Priority

If the same key is declared at a lower level, it overrides the value from the upper level. Priority: Step env > Job env > Workflow env

Step env  >  Job env  >  Workflow env
(highest)                  (lowest)

Three-Level Environment Variable Example

# Level 1: Workflow level (available in all Jobs/Steps)
env:
  APP_NAME: my-app
  LOG_LEVEL: info

jobs:
  build:
    # Level 2: Job level (available in all Steps of this Job)
    env:
      LOG_LEVEL: debug    # Overrides Workflow's info with debug
      BUILD_TARGET: dist

    steps:
      - name: build
        run: |
          echo $APP_NAME      # "my-app"    (inherited from Workflow)
          echo $LOG_LEVEL     # "debug"     (overridden by Job)
          echo $BUILD_TARGET  # "dist"      (defined at Job)
          echo $EXTRA         # "step-only" (defined at Step)
        # Level 3: Step level (available only in this Step)
        env:
          EXTRA: step-only
          LOG_LEVEL: trace  # Overrides Job's debug with trace

Using Secrets

Sensitive values are referenced via the secrets context. Use Expressions in the value of environment variables.

env:
  # Correct usage — use Expression in value
  API_KEY: "${{ secrets.API_KEY }}"
  DB_PASSWORD: "${{ secrets.DB_PASSWORD }}"

jobs:
  deploy:
    env:
      DEPLOY_TOKEN: "${{ secrets.DEPLOY_TOKEN }}"
    steps:
      - name: deploy
        run: ./deploy.sh
        env:
          # Secrets can also be referenced at the Step level
          AWS_ACCESS_KEY: "${{ secrets.AWS_ACCESS_KEY_ID }}"

Using Variables

Variables set at the organization/repository level are referenced via the vars context.

env:
  DEPLOY_ENV: "${{ vars.DEPLOY_ENV }}"
  REGION: "${{ vars.AWS_REGION }}"

jobs:
  deploy:
    steps:
      - name: deploy
        run: |
          echo "Deploying to $DEPLOY_ENV in $REGION"
          ./deploy.sh

env Keys and Expressions

Expressions cannot be used in env keys. Keys must be literal strings; Expressions can only be used in values.

# Incorrect usage — Expression cannot be used in key
env:
  ${{ secrets.KEY_NAME }}: some-value

# Correct usage — key is a literal string, Expression used in value
env:
  API_KEY: "${{ secrets.API_KEY }}"
  APP_VERSION: "${{ vars.APP_VERSION }}"
  COMMIT_SHA: "${{ collabops.sha }}"

Rules

env keys must be literal strings.

Expressions can only be used in values.

If the same key is declared at a lower level (Step > Job > Workflow), it overrides the upper-level value.

By convention, environment variable names use uppercase letters and _.