Environment Variables in GitHub Actions (with Docker Example)

Automation is at the heart of modern software delivery, and GitHub Actions has become a go-to solution for CI/CD pipelines. One of the most powerful features in GitHub Actions is the ability to manage environment variables (envs). These variables help control behavior, store configuration, and keep sensitive data secure.

In this article, we’ll explore different ways to declare and use environment variables in GitHub Actions, and we’ll tie it all together with a Docker build and push example.

What are Environment Variables?

Environment variables are key-value pairs that provide configuration settings to jobs, steps, or even the whole workflow. They can be used to:

Pass configurations (for example, Node.js version, Docker image name)
Control workflow behavior
Store sensitive information (API keys, tokens)

Types of Environment Variables in GitHub Actions

1. Workflow-level

Defined at the top of the workflow, available in all jobs and steps.

env:
  WORKFLOW_ENV: "workflow-scope"

2. Job-level

Defined under a job, only available within that job.

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      JOB_ENV: "job-scope"

3. Step-level

Defined under a step, only available within that step.

steps:
  - name: Step with env
    env:
      STEP_ENV: "step-scope"
    run: echo "Step var: $STEP_ENV"

4. Matrix-level

Useful for testing across multiple environments (for example, OS or language versions).

strategy:
  matrix:
    os: [ubuntu-latest, windows-latest]
    version: [14, 16]

Use with ${{ matrix.os }} or ${{ matrix.version }}.

5. Dynamic Environment Variables

Created at runtime with GITHUB_ENV.

- run: echo "BUILD_ID=${{ github.run_id }}" >> $GITHUB_ENV

6. Secrets

Used for sensitive values like tokens or API keys.

env:
  DOCKER_PASSWORD: ${{ secrets.DOCKER_PASSWORD }}

Real-world Example: Docker Build & Push

Let’s bring it together with a Docker pipeline.

name: Docker CI/CD

on:
  push:
    branches: [ main ]

env:
  IMAGE_NAME: myapp

jobs:
  docker:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        version: ["1.0", "2.0"]

    steps:
      - uses: actions/checkout@v3

      - name: Log in to Docker Hub
        uses: docker/login-action@v2
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}

      - name: Build Docker image
        run: |
          docker build . -t ${{ secrets.DOCKER_USERNAME }}/$IMAGE_NAME:${{ matrix.version }}

      - name: Push Docker image
        run: |
          docker push ${{ secrets.DOCKER_USERNAME }}/$IMAGE_NAME:${{ matrix.version }}

Explanation of this example:

Workflow-level: IMAGE_NAME is available everywhere.
Matrix-level: Builds multiple versions of the Docker image.
Secrets: Docker credentials are securely injected from GitHub Secrets.

Visualizing Env Scopes

Workflow → Job → Step
         ↓        ↓
     Matrix    Dynamic/Secrets

This flow shows how variables cascade down from workflow to job to step, while matrix, dynamic, and secrets act as overlays.

Key Takeaways

Use workflow-level environment variables for common configurations.
Use job-level environment variables to scope variables to a specific job.
Use step-level environment variables sparingly for unique cases.
Use matrix environment variables to test multiple versions or environments.
Use dynamic environment variables when values need to be generated at runtime.
Use secrets for sensitive information such as credentials and tokens.

Conclusion

Environment variables are a cornerstone of GitHub Actions workflows. Whether you’re building, testing, or deploying with Docker, managing environment variables correctly ensures your pipeline is clean, secure, and maintainable.

By combining these scopes effectively, you can design workflows that adapt easily to new environments and use cases.

Environment Variables in GitHub Actions (with Docker Example)

Comments

More from this blog

Automating Linux User Lifecycle with GitHub Actions: A Practical DevOps Guide

HashiCorp Vault Secrets & GitHub Actions: Centralized Secret Management

Qwen: The AI-Powered Assistant for DevOps and Beyond

Understanding GitHub Actions Concurrency

Organization-level Environment Variables and Secrets in GitHub Actions

What are Environment Variables?

Types of Environment Variables in GitHub Actions

1. Workflow-level

2. Job-level

3. Step-level

4. Matrix-level

5. Dynamic Environment Variables

6. Secrets

Real-world Example: Docker Build & Push

Explanation of this example:

Visualizing Env Scopes

Key Takeaways

Conclusion

Command Palette

Comments

More from this blog

What are Environment Variables?

Types of Environment Variables in GitHub Actions

1. Workflow-level

2. Job-level

3. Step-level

4. Matrix-level

5. Dynamic Environment Variables

6. Secrets

Real-world Example: Docker Build & Push

Explanation of this example:

Visualizing Env Scopes

Key Takeaways

Conclusion