How to Manage GitHub Actions Environment Variables and Secrets

Muhammed Ali

Read more posts by this author.

If you are new to GitHub Actions environmental variables, you may have yet to learn how to store them. But is it possible? Yes!

In this tutorial, you will learn different ways to save your GitHub Action environment variables and secrets you can use when required while working with GitHub Actions.

Ready? Read on to get started!

Prerequisites

This tutorial will be a hands-on demonstration that requires any operating system with Git installed will work, Ubuntu OS is used in the tutorial. In addition, a basic working knowledge of Git operations is necessary to commit code to a GitHub repository.

Setting Environmental Variables for GitHub Actions

When automating processes with GitHub Actions workflow, you may come across a need to attach environment variables to your workflows. How? You first need to create and specify custom environment variables in the workflow with the env keyword.

1. Create a directory named .github/workflows where you’ll store your workflow file.

2. Next, create a file with your preferred name in the .github/workflows directory. But for this example, the file is named main.yml. Copy and paste the code below to the main.yml file.

The code below sets and displays the API_KEY environment variable when the code triggered the workflow.

name: env_tutorial
## Triggers the workflow on when there is a push, or 
## pull request on the main branch
on: [pull_request, push] 

env:
  ## Sets environment variable
  API_KEY: XXXXXXXXXXXX    

jobs:
  job1:
    ## The type of runner that the job will run on, 
    ## here it runs on ubuntu latest
    runs-on: ubuntu-latest 
    steps:
      - name: step 1
        ## Reference your environment variables
        run: echo "The API key is:${{env.API_KEY}}"   

  job2:
    runs-on: ubuntu-latest
    steps:
      - name: step 1
        ## Another way reference your environment variables
        run: echo "The API key is:$API_KEY"

3. Commit and push the code to your GitHub repository.

git add .
git commit -m "update"
git push
Pushing updates to the GitHub repository
Pushing updates to the GitHub repository

4. Now, open your web browser and navigate to your project on GitHub. Click on the Actions tab, then click on your current commit.

You will see something like the image below, which shows that GitHub has run the workflow.

GitHub actions for repository
GitHub actions for repository

5. Finally, click on either job1 or job2, and you will see that you’ve successfully referenced the environment variable you initialized.

Viewing Referenced Environment Variable (job1)
Viewing Referenced Environment Variable (job1)
Viewing Referenced Environment Variable (job2)
Viewing Referenced Environment Variable (job2)

Defining an Environment Variable for a Job

Now that you’ve initialized the environment variable throughout the workflow file, any job can reference the environment variable. But perhaps you only want one job to reference the environment variable. If so, place the env keyword in the job itself.

1. Replace the code in your main.yml file with the code below.

The code below shows that when you place the environment variable in a particular job, other jobs cannot reference the environment variable.

name: env_tutorial
## Triggers the workflow on when there is a push, or 
## pull request on the main branch
on: [pull_request, push] 

jobs:
  job1:
    ## The type of runner that the job will run on
    runs-on: ubuntu-latest 
    env:
      ## Environment variable
      API_KEY: XXXXXXXXXXXX    
    steps:
      - name: step 1
        ## Reference your environment variables
        run: echo "The API key is:${{env.API_KEY}}"   

  job2:
    runs-on: ubuntu-latest
    steps:
      - name: step 1
        ## Another way reference your environment variables
        run: echo "The API key is:$API_KEY"  

2. Commit your changes and push jobs from your code to GitHub like you did in the previous section.

3. Finally, navigate to your project on GitHub, then click on both job1 and job2 to see their comparison:

  • job1 – You’ll see that you’ve referenced the environment variable perfectly.
  • job2 – The API key is blank.
Viewing Referenced Environment Variable (job1)
Viewing Referenced Environment Variable (job1)
Viewing Referenced Environment Variable (job2)
Viewing Referenced Environment Variable (job2)

Defining an Environment Variable for a Step

Now that you have learned how to specify environment variables within a job, you must be wondering how you can do the same with the steps.

For the steps in a job, you specify the environment variable within the step as you did for the job.

1. Replace the code you have on your main.yml file with the code below.

In the code below, you specify the environment variable in step 1 but not in step 2, and you’ll see the effect in the following steps.

name: env_tutorial
## Triggers the workflow on when there is a push, or 
## pull request on the main branch
on: [pull_request, push] 

jobs:
  job1:
    ## The type of runner that the job will run on
    runs-on: ubuntu-latest 
    steps:
      - name: step 1
        env:
          ## Environment variable for step 1
          API_KEY: XXXXXXXXXXXX    
        ## Reference your environment variables
        run: echo "The API key is:${{env.API_KEY}}"   
      - name: step 2
        ## Reference your environment variables
        run: echo "The API key is:${{env.API_KEY}}"   

2. Now commit the changes and push the code to GitHub.

3. Finally, navigate to your project on GitHub, and click on job1.

Even though you reference the two API keys in the same job (job1) in both steps, step 2 couldn’t assess the API key (blank), as shown below. Why? Because you didn’t specify the environment variable within step 2 in your code.

Setting environment variables for steps
Setting environment variables for steps

Managing Environment Variables via GitHub Secrets

Instead of hard-coding, you may want to store your environment variable securely, and GitHub secrets can do just that. GitHub encrypts the values you put in secrets, so they are not visible nor readable in the naked eye.

The secret created with this method is accessible to the entire workflow, jobs, and steps; there are no restrictions.

To store your environment variable in GitHub Secrets:

1. First, push your code to GitHub as you did in the previous sections.

2. Next, navigate to your project on GitHub and click on the Settings tab.

Click on Secrets in the tab below to start adding a secret.

Storing environment variables in Secrets
Storing environment variables in Secrets

3. Next, click on the New repository secret, and you’ll see a form to fill in details about the secret you’re adding.

Creating new repository secret
Creating new repository secret

4. Fill in the form appropriately (Name and Value) and click the Add secret button to submit. Now the API_KEY is saved in GitHub Secrets. In this form, GitHub securely sets environment variables as secrets that you can reference when working on GitHub Actions.

Filling name and value of the new secret
Filling name and value of the new secret

5. Edit your main.yml file and replace the env keyword with secrets.

Below, you can see that you reference the API key in this ${{secrets.API_KEY}} format instead of hard-coding the API key itself.

name: env_tutorial
## Triggers the workflow on when there is a push, or 
## pull request on the main branch
on: [pull_request, push] 

jobs:
  job1:
    ## The type of runner that the job will run on
    runs-on: ubuntu-latest 
    steps:
      - name: step 1
        ## Reference your environment variables
        run: echo "The API key is:${{secrets.API_KEY}}"   

  job2:
    runs-on: ubuntu-latest
    steps:
      - name: step 1
        ## Reference your environment variables
        run: echo "The API key is:${{secrets.API_KEY}}"  

6. Finally, commit and push the code to GitHub, and navigate to your project on GitHub. Reference the first section.

You’ll see something like the image below, but you can’t see the actual API_key since GitHub encrypts the values you put in secrets.

Displaying API key from GitHub secrets
Displaying API key from GitHub secrets

Referencing Default GitHub Environment Variables

There are a couple of default environment variables provided by GitHub, which you can use to access filesystems in the repository instead of hard-coding paths. Default GitHub environment variables enable you to be more dynamic when referencing environment variables given to you by GitHub.

Some of the paths you can get with the default environment variables are as follow:

  • GITHUB_JOB – Provides job_id of the current job.
  • GITHUB_ACTION – Provides the id of the current action
  • GITHUB_ACTION_PATH – Provides the path where your action is located.
  • GITHUB_ACTOR – provides the name of the person or app that initiated the workflow, like your GitHub username.
  • GITHUB_RUN_ID – provides the unique number of the run command.

Replace what you have in your main.yml file with the code below. The code below displays the default environment variable stated in the code.

name: env_tutorial
## Triggers the workflow on when there is a push or 
## pull request on the main branch
on: [pull_request, push] 

jobs:
  job1:
    ## The type of runner that the job will run on
    runs-on: ubuntu-latest 
    steps:
      - name: step 1
        run: |
          echo "The job_id is: $GITHUB_JOB"   # reference the default environment variables
          echo "The id of this action is: $GITHUB_ACTION"   # reference the default environment variables
          echo "The run id is: $GITHUB_RUN_ID" 
          echo "The GitHub Actor's username is: $GITHUB_ACTOR"
      - name: step 2
        run: |
          echo "The run id is: $GITHUB_RUN_ID"

Commit and push the code changes to GitHub, check your actions in your GitHub project, and you will see something like the image below.

Referencing the Default GitHub environment variables
Referencing the Default GitHub environment variables

Conclusion

Throughout this tutorial, you’ve learned how to manage GitHub Actions environment variables. You should now have a foundational knowledge of storing environment variables securely and how to use default ones provided by GitHub.

Now how do you plan to incorporate this newfound knowledge when working with GitHub Actions? Perhaps saving the API keys required for deployment?

Subscribe to Stay in Touch

Never miss out on your favorite ATA posts and our latest announcements!

Looks like you're offline!