Guide to GitHub Actions variables

Variables in GitHub Actions can simplify complex workflows, making them easier to manage and understand. This guide will explore how to set variables, the default environment variables provided by GitHub, and how to effectively use these variables in your workflows.

GitHub Actions default environment variables

GitHub Actions provides a set of default environment variables that are automatically available within your workflow. These variables can provide useful context such as the branch name, commit SHA, repository details, and more. Some commonly used default environment variables include:

• GITHUB_REPOSITORY: The owner and repository name. For example, octocat/Hello-World.
• GITHUB_SHA: The commit SHA that triggered the workflow.
• GITHUB_REF: The branch or tag ref that triggered the workflow.
• GITHUB_WORKFLOW: The name of the workflow.
• GITHUB_ACTOR: The name of the person or app that initiated the workflow.
• GITHUB_WORKSPACE: The GitHub workspace directory path.

These variables are particularly useful for scripting within your workflows, allowing you to adapt behavior based on the context of the run.

Accessing environment variables

To access environment variables in your steps, you can use them directly in your scripts or actions. For shell commands, they can be accessed just like any other environment variable in your execution environment:

steps:
  - name: Print environment variables
    run: |
      echo "Repository name: $GITHUB_REPOSITORY"
      echo "Branch name: $GITHUB_REF"

Setting variables in GitHub Actions

You can set variables in GitHub Actions in several ways:

Environment variables in GitHub Actions workflow files

You can define environment variables directly in your workflow file for use across multiple jobs or specify them for single jobs:

Workflow-level

name: Example workflow
on: push
env:
  GLOBAL_ENV_VAR: 'Global Value' # This variable is available to all jobs
jobs:
  example_job:
    runs-on: ubuntu-latest
    steps:
      - name: Use global environment variable
        run: echo $GLOBAL_ENV_VAR

This example sets the variable in the global context, allowing you to use it across all jobs in the workflow file.

Job-level

jobs:
  example_job:
    runs-on: ubuntu-latest
    env:
      JOB_LEVEL_VAR: 'Job-specific Value' # This variable is only available in this job
    steps:
      - name: Use job level environment variable
        run: echo $JOB_LEVEL_VAR

This example sets the variable in the job context, restricting its use to a singular job. This is useful if the variable is job-specific and will change across different jobs.

Setting variables dynamically

To set variables dynamically during job execution, you can use the echo command with the >> operator to set an environment variable that will be used in subsequent steps. For example:

steps:
  - name: Set dynamic variable
    run: echo "DYNAMIC_VAR=dynamic value" >> $GITHUB_ENV

  - name: Use dynamic variable
    run: echo $DYNAMIC_VAR

This method leverages the $GITHUB_ENV file to append environment variables, which are then accessible in later steps within the same job.

Security best practices

When using environment variables to manage sensitive information, such as credentials or API keys, it’s crucial to use secrets rather than plain environment variables. GitHub encrypts secrets, and they can be used in a similar manner to environment variables in your workflows:

steps:
  - name: Use secrets
    env:
      SUPER_SECRET: ${{ secrets.SUPER_SECRET }}
    run: echo "Using secret value $SUPER_SECRET"

For further reading on GitHub Actions variables, see the official GitHub documentation.