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.

---