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
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
GITHUB_ENV environment file to set an environment variable that the following steps in a workflow can use. The environment file 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."
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.
|Always set to |
|The name of the workflow.|
|A unique number for each run within a repository. This number does not change if you re-run the workflow run.|
|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.|
|The unique identifier (|
|Always set to |
|The name of the person or app that initiated the workflow. For example, |
|The owner and repository name. For example, |
|The name of the webhook event that triggered the workflow.|
|The path of the file with the complete webhook event payload. For example, |
|The GitHub workspace directory path. The workspace directory is a copy of your repository if your workflow uses the actions/checkout action. If you don't use the |
|The commit SHA that triggered the workflow. For example, |
|The branch or tag ref that triggered the workflow. For example, |
|Only set for pull request events. The name of the head branch.|
|Only set for pull request events. The name of the base branch.|
|Returns the URL of the GitHub server. For example: |
|Returns the API URL. For example: |
|Returns the GraphQL API URL. For example: |
Note: If you need to use a workflow run's URL from within a job, you can combine these environment variables:
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
ifkeyword 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 more information, see "Contexts."
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.
Note: GitHub reserves the
GITHUB_ environment variable prefix for internal use by GitHub. Setting an environment variable or secret with the
GITHUB_ prefix will result in an error.
Any new environment variables you set that point to a location on the filesystem should have a
_PATH suffix. The
GITHUB_WORKSPACE default variables are exceptions to this convention because the words "home" and "workspace" already imply a location.