C. Chandrasekara, P. HerathHands-on GitHub Actionshttps://doi.org/10.1007/978-1-4842-6464-5_3

3. Variables

Chaminda Chandrasekara¹ and Pushpa Herath²

(1)

Dedigamuwa, Sri Lanka

(2)

Hanguranketha, Sri Lanka

In any platform or tool facilitating the implementation of CI/CD, it is essential to have a mechanism to configure variables in the pipelines, depending on the different scopes of the pipeline implementation. This chapter explores the options for setting up GitHub Actions variables, how to scope them, naming conventions for variables, and the default variables in workflows.

Defining and Using Variables

In GitHub Actions, you can define custom variables in the scope of a workflow, job, or step. Variables can be created or modified using commands in a workflow’s steps or actions.

Variables in the Entire Workflow Scope

Let’s first identify how to define a variable in the scope of an entire workflow. You can use the following syntax at the workflow level to define the entire workflow’s variables.

env:

varname1: value1

varname2: value2

The following is an example.

env:

user_name: "Chaminda"

demo_name: "Variable Demo"

To utilize an environment variable in a step, you can use the variable's name with $varname syntax. The following step is an example.

steps:

- name: Using Workflow Variables

run: echo Hello, $user_name!

Welcome to $demo_name!!!

The following is a full workflow implementation using these variables.

on: [push]

env:

user_name: "Chaminda"

demo_name: "Variable Demo"

jobs:

VariableUsageJob:

runs-on: ubuntu-latest

steps:

- name: Using Workflow Variables

run: echo Hello, $user_name!

Welcome to $demo_name!!!

Variables in Job Scope

When defining variables in a job scope, you must use the same syntax as the workflow scope variables. For example, the following shows a variable defined in the job scope.

jobs:

VariableUsageJob:

runs-on: ubuntu-latest

env:

job_var1: "job variable value"

Variables in Step Scope

The same syntax can be used to define variables in a step scope. The following is an example.

jobs:

VariableUsageJob:

runs-on: ubuntu-latest

env:

job_var1: "job variable value"

steps:

- name: Using Workflow Variables

env:

step_var1: "Step Variable Value"

The following is an example workflow with all levels of variables defined.

on: [push]

env:

user_name: "Chaminda"

demo_name: "Variable Demo"

jobs:

VariableUsageJob:

runs-on: ubuntu-latest

env:

job_var1: "job variable value"

steps:

- name: Using Workflow Variables

run: echo Hello, $user_name!

Welcome to $demo_name!!!

here is job var1 $job_var1

here is step var1 $step_var1

env:

step_var1: "Step Variable Value"

Using the set-env Command

The set-env command lets you create a new variable or change an existing variable's value. However, the variable created or value changed is not visible in the current action or the step. It is only available in subsequent steps or actions in the job. To set the value of a variable or create a new variable, you can use the following syntax.

echo "::set-env name=varname::varvalue"

You can set the variable user_name value to a different value, as shown in the following example.

echo "::set-env name=user_name::Chandrasekara"

The following example of a full workflow can be used for further reference.

on: [push]

env:

user_name: "Chaminda"

demo_name: "Variable Demo"

jobs:

VariableUsageJob:

runs-on: ubuntu-latest

env:

job_var1: "job variable value"

steps:

- name: Using Workflow Variables

run: echo Hello, $user_name!

Welcome to $demo_name!!!

here is job var1 $job_var1

here is step var1 $step_var1

env:

step_var1: "Step Variable Value"

- name: Set user_name Varaible

run: echo "::set-env name=user_name::Chandrasekara"

- name: Set new_var Varaible

run: echo "::set-env name=new_var::newvarvalue"

- name: Using Variables

run: echo Hello, $user_name!

Welcome to $demo_name!!!

here is job var1 $job_var1

here is new_var $new_var

This section identified the options to define custom environment variables in a GitHub Actions workflow with syntax references. It explained how to use the variables in the workflow steps or actions. Additionally, it looked at how to change a variable value or create a variable via an action using the set-env command.

Default Variables

A GitHub Actions workflow has a set of default variables.

CI: This variable value is always set to true.
HOME: The home directory in the runner storing user data in the workflow.
GITHUB_WORKFLOW: GitHub workflow name.
GITHUB_RUN_ID: In a repo, each workflow run has a unique number. When rerunning an existing run, it does not change the run ID.
GITHUB_RUN_NUMBER: The number for each run of the given workflows. If a repo has more than one workflow, the second or any other workflow’s first run begins with the number 1. If you re-run an existing workflow run, this number does not change.
GITHUB_ACTION: The action’s identification.
GITHUB_ACTIONS: This variable value is true if an action is running in a job. It identifies whether an action is running or not.
GITHUB_ACTOR: The name of the person or app that initiated the workflow.
GITHUB_REPOSITORY: The repository name and the owner. For example, chamindac/variabledemo.
GITHUB_EVENT_NAME: The name of the webhook event that triggers the workflow.
GITHUB_EVENT_PATH: The path of the file containing the payload of the webhook event which has triggered the workflow.
GITHUB_WORKSPACE: This is the work directory in the job runner machine of the workflow. When actions/checkout action is used, a folder is created with the repo content inside the workspace folder. If the actions/checkout action is not used, the folder would be empty.
GITHUB_SHA: The commit SHA that triggers the workflow.
GITHUB_REF: The branch or tag ref that triggers the workflow. This variable is not available if the event triggering the workflow does not have a branch or tag.
GITHUB_HEAD_REF: When a workflow is based on a forked repo, this variable contains the branch of the head repository.
GITHUB_BASE_REF: When a workflow is based on a forked repo, this variable contains the branch of the base repository.
GITHUB_SERVER_URL: The URL of the GitHub server (https://github.com).
GITHUB_API_URL: The API URL (https://api.github.com).
GITHUB_GRAPHQL_URL: The GraphQL API URL (https://api.github.com/graphql).

Depending on your repo’s language/framework and based on the steps/actions to set up those frameworks in the workflow job runner, you might get additional predefined variables that can be used in your workflow. For example, when you are using .NET Core, you can use it in GitHub Actions using the following syntax in your workflow job. Note that the following workflow segment uses .NET Core 2.1.

jobs:

build-and-deploy:

runs-on: ubuntu-latest

steps:

- uses: actions/checkout@master

- name: Set up .NET Core

uses: actions/setup-dotnet@v1

with:

dotnet-version: '2.1.804'

Once you use action/setup-dotnet, you can use a set of variables documented at https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet#environment-variables in your workflow. The following example is a workflow in which a .NET Core web app is built and published to a dotnet core runtime path using the DOTNET_ROOT variable.

on:

push:

branches:

- master

jobs:

build-and-deploy:

runs-on: ubuntu-latest

steps:

- uses: actions/checkout@master

- name: Set up .NET Core

uses: actions/setup-dotnet@v1

with:

dotnet-version: '2.1.804'

- name: Build with dotnet

run: dotnet build --configuration Release

- name: dotnet publish

run: dotnet publish -c Release -o ${{env.DOTNET_ROOT}}/myapp

We identified the predefined variables available in a GitHub Actions workflow and saw how to get additional variables according to the language/framework.

Naming Considerations for Variables

GitHub Actions workflows allow you to define custom environment variables in a scoped workflow, job, or step. However, when defining your custom variables, there are a couple of things you must consider.

GITHUB_ Prefix

The GITHUB_ prefix is reserved for GitHub. You cannot use it in naming custom environment variables. If you try to use GITHUB_, it results in an error in the workflow.

Case Sensitivity

GitHub variables are case sensitive. Hence, a variable name and its usage should use the same case, or else the variable value cannot be retrieved in the usage location of the workflow.

_PATH Suffix

The variables you define to point to a filesystem location should contain the _PATH suffix. However, the HOME and GITHUB_WORKSPACE default variables do not use this convention because the words home and workspace imply a location.

Special Characters

Even though there are no syntactical errors caused by using special characters in the middle of a variable name, it is better to avoid them at all costs because such variables cannot be properly retrieved when used in workflow steps/actions. Using an underscore (_) to separate parts of a variable name is acceptable. Variable names must begin with an alphabetical character and may contain numbers in the middle or at the end of the name. However, the variable name should not begin with a number. Special characters other than _ should be avoided.

For example, valid variables to use are only user_name, demo_name, and my1_var1, out of the all the variables below, even though none of them is giving any syntax errors.

on: [push]

env:

user_name: "Chaminda"

demo_name: "Variable Demo"

my@newvar@$: "specialvarval"

$varwith$: "valwith$"

1mynewnumvar: "numvarval"

my-var: "DashVarvalue"

my1_var1: "my1_var1value"

In this section we have looked at considerations in creating custom variables in GitHub Actions workflows.

Summary

This chapter discussed using custom environment variables and the default variables available in GitHub Actions workflows and used a .NET Core example. It also discussed naming conventions for variables.

The next chapter explores the use of secrets and tokens in GitHub Actions workflows.