Using environment variables in GitHub Actions

Environment variables in GitHub Actions are useful for managing configurations separately from code, allowing workflows to be more dynamic and secure. This guide will cover how to set and use environment variables in GitHub Actions.

Understanding environment variables in GitHub Actions

Environment variables are dynamic named values that can affect the way jobs run in individual workflows. In GitHub Actions, they are used to pass configuration data into your workflows and actions. This can include sensitive information, settings, file paths, and other data that should not be hardcoded in your workflow files.

Types of environment variables in GitHub Actions

1. Built-in environment variables: GitHub provides default environment variables such as GITHUB_SHA for the commit SHA, GITHUB_REF for the branch or tag ref that triggered the workflow, and others that provide context about the run.

2. Custom environment variables: These are user-defined and can be set at various scopes—globally for all jobs, at the job level, or within a single step.

How to set environment variables in GitHub Actions

Setting global environment variables

To define environment variables that are available to all jobs and steps in a workflow, you can use the env key at the top level of your workflow file:

name: Example workflow
on: [push]
env:
  GLOBAL_VAR: 'GlobalValue' # Global environment variable accessible to all jobs and steps

jobs:
  example_job:
    runs-on: ubuntu-latest
    steps:
      - name: Use global environment variable
        run: echo $GLOBAL_VAR # Uses the global environment variable

Setting job-specific environment variables

You can also set environment variables that are only available to a specific job. This is done by including an env key within an individual job:

jobs:
  job1:
    runs-on: ubuntu-latest
    env:
      JOB_VAR: 'JobSpecificValue' # Environment variable only for this job
    steps:
      - name: Use job-specific environment variable
        run: echo $JOB_VAR # Outputs the job-specific variable

Setting environment variables for a single step

To set environment variables that are only available within a single step, include an env key directly within the step:

steps:
  - name: Set step-specific environment variables
    env:
      STEP_VAR: 'StepSpecificValue'
    run: echo $STEP_VAR # Outputs the step-specific variable

Using secrets as environment variables

Sensitive information such as passwords, tokens, and API keys should be stored in GitHub Secrets and accessed via environment variables within your workflows:

steps:
  - name: Use secrets
    env:
      SENSITIVE_VAR: ${{ secrets.SECRET_NAME }}
    run: ./my_login_script $SENSITIVE_VAR

This method keeps your sensitive data secure by preventing it from being exposed in logs or hardcoded in your repository.

Practical examples of using environment variables

Example 1: Configuring a deployment

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      ENVIRONMENT: production
      DEPLOY_PATH: /var/www/html
    steps:
      - name: Deploy to production
        run: |
          echo "Deploying to $ENVIRONMENT"
          rsync -av --delete ./build/ user@server:$DEPLOY_PATH

Example 2: Integrating with third-party services

jobs:
  notify:
    runs-on: ubuntu-latest
    steps:
      - name: Send notification
        env:
          API_KEY: ${{ secrets.API_KEY }}
        run: |
          curl -X POST -d "message=Build completed" https://api.notification.service/send?key=$API_KEY

For further reading on GitHub Actions environment variables, see the official GitHub docs.