How to use GitHub Actions environment variables

GitHub Actions is a powerful tool that can be used to store your code and automate your workflows. One key feature that makes GitHub Actions versatile is environment variables.

In this guide, I will explore how to effectively use environment variables in GitHub Actions.

Introduction to Environment Variables

Environment variables are values that are stored outside of your source but can be accessed by your code at any time.

Often you will see environment variables used to store sensitive information such as API keys, connection strings, credentials, and the like.

By using environment variables you are separating the configuration from your code base making it easy to manage and share across different environments.

Within GitHub Actions there are three methods you can use environment variables:

  • Use environment variables for a specific job
  • Use environment variables within a specific step within a job
  • Use environment variables throughout a GitHub Action workflow

Let’s explore these options.

Use environment variables for a specific job

There are times when you will want to use a variable for a specific part of your automation. It helps to give you granular control for that part of the automation process.

If we built a GitHub Action workflow you’ll be able to see how that would work.

Below is the code for a simple GitHub Action workflow that will write a sentence to the console.

On line 11 we are declaring “env”. Which are environment variables. We then have a line of code below that declares the name of our environment variable “input_value” and then the contents of that variable is “env-variable-specific-job”.

name: Specific job - example environment variable
 
on:
  push:
    branches:
    - main
 
jobs:
  environment_variables_examples:
    runs-on: ubuntu-latest
    env:
    	input_value: env-variable-specific-job
    steps:
      - name: “Test to show environment variable”
     

The environment variable is declared within the job section of the workflow. That environment variable can only be used within that job.

Use environment variables within a specific step within a job

What about a more specific use case, what if you want the variable to only be used within a specific step? You can do that as well.

Again let’s build a simple workflow to show how it works. We’ll use the same kind of example as below, where we output some information to the console.

Looking at the code below you can see we’ve moved the declaration of environments from line 11 to line 17. The environment variable is declared within a specific step. In our example case step 2.

name: Specific step - example environment variable
 
on:
  push:
    branches:
    - main
 
jobs:
  environment_variables_examples:
    runs-on: ubuntu-latest

    steps:
      - name: “Step 1”
        run: echo "This is step 1. The environment variable for this example is $input_value."
      - name: “Step 2”
        run: echo "This is step 2. The environment variable for this example is $input_value."
        env:
    	input_value: env-variable-specific-step

If we run that workflow you can see from the result below, step 1 doesn’t have access to the environment variable so it doesn’t output it, but step 2 does.

Environment variable output example

Use environment variables throughout a GitHub Action workflow

More commonly you’ll want to declare an environment variable that can be used throughout your entire workflow.

Let’s look at how you would declare that and where you would declare it.

We declare the environment variable on line 8 now. It’s near the start of our workflow configuration.

This means we can call the environment variable at any point within the workflow. Within any job or any step.

name: Workflow - example environment variable
 
on:
  push:
    branches:
    - main

env:
    input_value: env-variable-workflow
 
jobs:
  environment_variables_examples:
    runs-on: ubuntu-latest

    steps:
      - name: “Step 1”
        run: echo "The environment variable for this example is $input_value."

Best Practices for Using Environment Variables

To ensure the effective and secure use of environment variables in your GitHub Actions workflows it’s important to follow some best practices:

Use secrets for sensitive data: What you will have noticed in the examples is that the environment variable is declared in plain text. Which isn’t ideal. Within the real world, you would combine environment variables and GitHub Action secrets.

And that will give you real power to hide sensitive information from your code and also separate it from your code base.

Use descriptive variable names: Choose meaningful names for your environment variables to improve the readability and maintainability of your workflows.

Regularly review and update variables: Periodically review and update your environment variables to ensure they are up to date and remove any unnecessary or outdated variables.

By following these best practices, you can ensure the secure and efficient use of environment variables in your GitHub Actions workflows.

Next Steps

Start to build and use environment variables within your GitHub Action workflows and understand the power of them to help you with your automation processes!