Environment Variables & Configs

Environment variables and configuration are the non-sensitive, per-environment values that tell an application how to behave when it runs — which database to connect to, which API endpoint to call, what log level to use, whether a feature is enabled. As established in Lesson 23, these are distinct from secrets: they carry no inherent risk if seen, but they still vary between environments and must be injected into the application at runtime rather than hardcoded into the build. The pattern for doing this correctly is one of the most consequential decisions in CI/CD design, because getting it wrong means either rebuilding artifacts per environment or hardcoding values that make the artifact untestable.

The Twelve-Factor App — Config as the Design Standard

The Twelve-Factor App methodology, published by Heroku engineers and widely adopted across the industry, defines a set of principles for building software that deploys cleanly across environments. Factor III — Config — states a simple test: could the codebase be made open source without exposing any credentials or environment-specific values? If the answer is no, configuration has leaked into the code.

The Twelve-Factor approach requires that all configuration be stored in environment variables — not in config files checked into version control, not in code constants, not in build-time flags. The application reads its configuration from the environment at runtime. The same artifact deployed to staging and production behaves differently because the environment variables differ, not because the artifact was built differently. This is the mechanism that makes "build once, deploy many" work in practice.

Environment Variables in GitHub Actions — Scoping and Precedence

GitHub Actions provides multiple levels at which environment variables can be defined, each with a different scope. Understanding the precedence order — which level wins when the same variable is defined at multiple levels — is essential for building pipelines that behave predictably across jobs and steps.

Config File Strategies — When Files Are Appropriate

Not all configuration is best delivered as environment variables. Structured configuration — complex nested objects, lists of values, multi-line connection strings — is often more readable and maintainable as a configuration file. The challenge is doing this without committing environment-specific values to version control.

Three patterns handle this well in CI/CD pipelines. The first is template substitution: commit a config template with placeholder variables (${DB_HOST}, ${LOG_LEVEL}), and use a tool like envsubst or sed in the pipeline to generate the final config file by substituting environment variables at deploy time. The second is config generation: the pipeline generates the config file from a script that reads environment variables and writes structured output. The third is a dedicated config service: AWS AppConfig, HashiCorp Consul, or Azure App Configuration — the application fetches its config at startup from a versioned, audited service rather than from files on disk.

Repository Variables — Config That Is Not Secret

GitHub Actions supports repository variables — a separate store from secrets, for values that vary per environment but do not need encryption. Repository variables are visible in the GitHub UI, can be read in workflow logs, and are intended for non-sensitive configuration: the name of the staging cluster, the ECR repository URL, the deployment region, the last known-good deployment SHA used for rollback.

Using repository variables for non-sensitive configuration and secrets for sensitive values keeps the secret store focused on what actually needs protection. It also makes debugging easier: when a deployment fails because the wrong cluster name was used, a variable is visible and auditable; a secret with the same value would be masked and invisible in logs, making the misconfiguration harder to identify.

env:                                       # Workflow-level — shared across all jobs
  NODE_VERSION: '20'
  APP_NAME: my-service
  REGISTRY: ghcr.io

jobs:
  deploy-staging:
    runs-on: ubuntu-latest
    environment: staging
    env:                                   # Job-level — only available in this job
      DEPLOY_ENV: staging
      CLUSTER: ${{ vars.STAGING_CLUSTER }} # Repository variable — visible, not encrypted

    steps:
      - uses: actions/checkout@v4

      - name: Generate config file from template
        run: |
          export DB_HOST=${{ vars.STAGING_DB_HOST }}     # Non-sensitive config from vars
          export LOG_LEVEL=debug
          envsubst < config/app.template.yaml > config/app.yaml
          # Substitutes ${DB_HOST} and ${LOG_LEVEL} in the template

      - name: Deploy
        env:
          DB_PASSWORD: ${{ secrets.DB_PASSWORD }}        # Sensitive — secret, step-scoped only
        run: |
          ./deploy.sh \
            --env "$DEPLOY_ENV" \
            --cluster "$CLUSTER" \
            --config config/app.yaml \
            --db-password "$DB_PASSWORD"

Practice Questions

Answer in your own words — then check against the expected answer.

Lesson Quiz