Working with environment variables - GitHub Actions (Part 2)

👉 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.

1. Custom Environment Variables .
2. Default Environment Variables.
3. 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.

1. Click on the settings in the repository
2. Click on the secrets
3. Click on the "New Repository Secret"
4. 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/