Environment variables

About environment variables

GitHub sets default environment variables that are available to every step in a workflow run. Environment variables are case-sensitive. Commands run in actions or steps can create, read, and modify environment variables.

To set custom environment variables, you need to specify the variables in the workflow file. You can define environment variables for a step, job, or entire workflow using the jobs.<job_id>.steps[*].env, jobs.<job_id>.env, and env keywords. For more information, see "Workflow syntax for GitHub."

jobs:
  weekday_job:
    runs-on: ubuntu-latest
    env:
      DAY_OF_WEEK: Mon
    steps:
      - name: "Hello world when it's Monday"
        if: ${{ env.DAY_OF_WEEK == 'Mon' }}
        run: echo "Hello $FIRST_NAME $middle_name $Last_Name, today is Monday!"
        env:
          FIRST_NAME: Mona
          middle_name: The
          Last_Name: Octocat

To use the value of an environment variable in a workflow file, you should use the env context. If you want to use the value of an environment variable inside a runner, you can use the runner operating system's normal method for reading environment variables.

If you use the workflow file's run key to read environment variables from within the runner operating system (as shown in the example above), the variable is substituted in the runner operating system after the job is sent to the runner. For other parts of a workflow file, you must use the env context to read environment variables; this is because workflow keys (such as if) require the variable to be substituted during workflow processing before it is sent to the runner.

You can also use the set-env workflow command to set an environment variable that the following steps in a job can use. The set-env command can be used directly by an action or as a shell command in a workflow file using the run keyword. For more information, see "Workflow commands for GitHub Actions."

Default environment variables

We strongly recommend that actions use environment variables to access the filesystem rather than using hardcoded file paths. GitHub sets environment variables for actions to use in all runner environments.

Environment variable	Description
CI	Always set to true.
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_JOB	The job_id of the current job.
GITHUB_ACTION	The unique identifier (id) of the action.
GITHUB_ACTION_PATH	The path where your action is located. You can use this path to access files located in the same repository as your action. This variable is only supported in composite actions.
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. For example, octocat.
GITHUB_REPOSITORY	The owner and repository name. For example, octocat/Hello-World.
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. For example, /github/workflow/event.json.
GITHUB_WORKSPACE	The GitHub workspace directory path, initially empty. For example, /home/runner/work/my-repo-name/my-repo-name. The actions/checkout action will check out files, by default a copy of your repository, within this directory.
GITHUB_SHA	The commit SHA that triggered the workflow. For example, ffac537e6cbbf934b08745a378932722df287a53.
GITHUB_REF	The branch or tag ref that triggered the workflow. For example, refs/heads/feature-branch-1. If neither a branch or tag is available for the event type, the variable will not exist.
GITHUB_HEAD_REF	Only set for pull request events. The name of the head branch.
GITHUB_BASE_REF	Only set for pull request events. The name of the base branch.
GITHUB_SERVER_URL	Returns the URL of the GitHub Enterprise Server server. For example: https://[hostname].
GITHUB_API_URL	Returns the API URL. For example: http(s)://[hostname]/api/v3.
GITHUB_GRAPHQL_URL	Returns the GraphQL API URL. For example: http(s)://[hostname]/api/graphql.
RUNNER_NAME	The name of the runner executing the job.
RUNNER_OS	The operating system of the runner executing the job. Possible values are Linux, Windows, or macOS.
RUNNER_TEMP	The path to a temporary directory on the runner. This directory is emptied at the beginning and end of each job. Note that files will not be removed if the runner's user account does not have permission to delete them.
RUNNER_TOOL_CACHE	The path to the directory containing preinstalled tools for GitHub-hosted runners. For more information, see "Specifications for GitHub-hosted runners".

Determining when to use default environment variables or contexts

GitHub Actions includes a collection of variables called contexts and a similar collection of variables called default environment variables. These variables are intended for use at different points in the workflow:

• Default environment variables: These variables exist only on the runner that is executing your job. For more information, see "Default environment variables."
• Contexts: You can use most contexts at any point in your workflow, including when default environment variables would be unavailable. For example, you can use contexts with expressions to perform initial processing before the job is routed to a runner for execution; this allows you to use a context with the conditional if keyword to determine whether a step should run. Once the job is running, you can also retrieve context variables from the runner that is executing the job, such as runner.os. For details of where you can use various contexts within a workflow, see "Context availability."

The following example demonstrates how these different types of environment variables can be used together in a job:

name: CI
on: push
jobs:
  prod-check:
    if: ${{ github.ref == 'refs/heads/main' }}
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying to production server on branch $GITHUB_REF"

In this example, the if statement checks the github.ref context to determine the current branch name; if the name is refs/heads/main, then the subsequent steps are executed. The if check is processed by GitHub Actions, and the job is only sent to the runner if the result is true. Once the job is sent to the runner, the step is executed and refers to the $GITHUB_REF environment variable from the runner.

Naming conventions for environment variables

When you set a custom environment variable, you cannot use any of the default environment variable names listed above with the prefix GITHUB_. If you attempt to override the value of one of these default environment variables, the assignment is ignored.

Any new environment variables you set that point to a location on the filesystem should have a _PATH suffix. The HOME and GITHUB_WORKSPACE default variables are exceptions to this convention because the words "home" and "workspace" already imply a location.