👉 Prerequisites
If you are new to GitHub Actions, I suggest you to read my Introduction to Github Actions - GitHub Actions (Part 1) article.
There are mainly three types of environment variables in GitHub Actions.
- Custom Environment Variables .
- Default Environment Variables.
- Encrypted Environment Variables.
1. Custom Environment Variables
Custom environment variables can be declared by ourselves inside any workflow file.
We can declare custom environment variables under different access scope in a workflow file.
- Workflow level
- Job level
- Steps level
So then the declared variable can be accessed by the particular scope only.
Example:
- Workflow level custom environment variables
Here I have declared a variable called PUBLICENV in workflow level and trying to echo it in different levels.
name: workflow-level-custom-environment-variables
on: [push]
# Here the environment variable is declared in workflow level
env:
PUBLICENV: Available for all jobs in this workflow
jobs:
sample-job-1:
runs-on: ubuntu-latest
steps:
- name: step-1
run: echo "${PUBLICENV}"
# This will echo the value/string of PUBLICENV
- name: step-2
run: echo "${PUBLICENV}"
# This will echo the value/string of PUBLICENV
sample-job-2:
runs-on: ubuntu-latest
steps:
- run: echo "${PUBLICENV}"
# This will echo the value/string of PUBLICENV
- Job level custom environment variables
Here I have declared a variable called JOBENV in "sample-job-1" level and trying to echo it in different levels.
name: job-level-custom-environment-variables
on: [push]
jobs:
sample-job-1:
env:
JOBENV: Available for this specific job only
# Here the environment variable is declared in job level
runs-on: ubuntu-latest
steps:
- name: step-1
run: echo "${JOBENV}"
# This will echo the value/string of JOBENV
- name: step-2
run: echo "${JOBENV}"
# This will echo the value/string of JOBENV
sample-job-2:
runs-on: ubuntu-latest
steps:
- run: echo "${JOBENV}"
# This will NOT echo the value/string of JOBENV
- Step level custom environment variables
Here I have declared a variable called STEPENV in "step-1" level inside the "sample-job-1" and trying to echo it in different levels.
name: step-level-custom-environment-variables
on: [push]
jobs:
sample-job-1:
runs-on: ubuntu-latest
steps:
- name: step-1
env:
STEPENV: Available for this specific job only
# Here the environment variable is declared in step level
run: echo "${STEPENV}"
# This will echo the value/string of STEPENV
- name: step-2
run: echo "${STEPENV}"
# This will NOT echo the value/string of STEPENV
sample-job-2:
runs-on: ubuntu-latest
steps:
- run: echo "${STEPENV}"
# This will NOT echo the value/string of STEPENV
2. Default Environment Variables
GitHub provides some default environment variables for many useful parameters of your repository. We can use them anywhere inside the workflow.
Here is a list of default env variables in GitHub Actions
- GITHUB_WORKFLOW The name of the workflow.
GITHUB_RUN_ID A unique number for each run within a repository. This number does not change if you re-run the workflow run.
GITHUB_RUN_NUMBER A unique number for each run of a particular workflow in a repository. This number begins at 1 for the workflow's first run, and increments with each new run. This number does not change if you re-run the workflow run.
GITHUB_ACTION The unique identifier (id) of the action.
GITHUB_ACTIONS Always set to true when GitHub Actions is running the workflow. You can use this variable to differentiate when tests are being run locally or by GitHub Actions.
GITHUB_ACTOR The name of the person or app that initiated the workflow.
GITHUB_REPOSITORY The owner and repository name.
GITHUB_EVENT_NAME The name of the webhook event that triggered the workflow.
GITHUB_EVENT_PATH The path of the file with the complete webhook event payload.
GITHUB_WORKSPACE The GitHub workspace directory path.
GITHUB_SHA The commit SHA that triggered the workflow.
GITHUB_REF The branch or tag ref that triggered the workflow.
GITHUB_HEAD_REF Only set for forked repositories. The branch of the head repository.
GITHUB_BASE_REF Only set for forked repositories. The branch of the base repository.
GITHUB_SERVER_URL Returns the URL of the GitHub server.
GITHUB_API_URL Returns the API URL.
GITHUB_GRAPHQL_URL Returns the GraphQL API URL.
Example:
name: default-environment-variables
on: [push]
jobs:
sample-job:
runs-on: ubuntu-latest
steps:
- name: echo-default-env-variables
run: |
echo "Home: ${HOME}"
echo "GITHUB_WORKFLOW: ${GITHUB_WORKFLOW}"
echo "GITHUB_ACTIONS: ${GITHUB_ACTIONS}"
echo "GITHUB_ACTOR: ${GITHUB_ACTOR}"
echo "GITHUB_REPOSITORY: ${GITHUB_REPOSITORY}"
echo "GITHUB_EVENT_NAME: ${GITHUB_EVENT_NAME}"
echo "GITHUB_WORKSPACE: ${GITHUB_WORKSPACE}"
echo "GITHUB_SHA: ${GITHUB_SHA}"
echo "GITHUB_REF: ${GITHUB_REF}"
Outputs:
3. Encrypted Environment Variables
In GitHub Actions, we can create encrypted environment variables as well. We can use GitHub Secrets to store API keys and passwords kind of things.
- Click on the settings in the repository
- Click on the secrets
- Click on the "New Repository Secret"
- Give YOUR_SECRET_NAME and the VALUE and click on the "Add Secret"
Example:
Here is an example code how we can re use encrypted variables without exposing the value.
name: working-with-encrypted-environment-variables
on:
push:
branches: [main, develop]
jobs:
sample-job:
runs-on: ubuntu-latest
steps:
- name: Deploy-to-staging
if: github.event_name == 'push' && github.ref == 'refs/heads/develop'
# Here this will be triggered only when the "push" event is performed only to the specific "develop" branch
run: npx surge --project ./build --domain eight-circle.surge.sh
env:
SURGE_LOGIN: ${{secrets.SURGE_LOGIN}}
SURGE_TOKEN: ${{secrets.SURGE_TOKEN}}
# SURGE_LOGIN & SURGE_TOKEN is stored as github secrets
👏 Bonus Tip :
In the Actions log screen, when any step is passed, it indicates a green check mark and when a step is failed, it indicates a red check mark but we can not see the exact error there unless enabling debugging.
To enable debugging in GitHub Actions, store these two encrypted environment variables in github secrets in the perticular repository. Then when a step is failed, you will see debug messages in the same log screen & it makes you easier to debug your errors.
Secret : ACTIONS_STEP_DEBUG
Value : TRUE
Secret : ACTIONS_RUNNER_DEBUG
Value : TRUE
👉 What's Next?
Working with external actions - GitHub Actions (Part 3)
Thank You
Hope you all enjoyed and learned something from this. Let me know your comments and suggestions in the discussion section.
👉 Visit me - https://mihinduranasinghe.com/
Top comments (6)
Hi Drallas,
Thank you and thank you very much for informing. I have fixed the links.
can we add a variable file to be referred for each environment incase if we have more variables to be referred?
Hi Mihindu,
Thank you very much for the series. Just have a quick question on default env. How do I access the default env variables, GITHUN_RUN_NUMBER, inside a makefile, which is part of the github workflow? I tried ${..}, and $(..), and both did not work. Thanks.
Hi Mihindu,
I would like to remove “actions” tab on my github private repository as well as restrict users from clicking on " Run workflow " on my environment ( QA ) inside my private repository.
I would like to know how to review and approve “Run workflow” in an environment ( QA ) inside my private repository.
Please advice how this can be achieved in github actions.
Regards,
Anil Kumar V.
Quick question..., is there a way to update a global env variable in order to share data across all jobs (without job outputs just some kind of global memory shared)