Virtual environments for GitHub Actions

GitHub uses hosted virtual machines to run workflows. The virtual machine contains an environment of tools, packages, and settings available for GitHub Actions to use.

GitHub Actions is currently in limited public beta and is subject to change. We strongly recommend that you do not use this feature for high-value workflows and content during the beta period.

For more information, see "About GitHub Actions."

In this article

About virtual environments

The GitHub Actions virtual environments are hosted on virtual machines in Microsoft Azure with the GitHub Actions runner installed. The GitHub Actions runner is a fork of the Azure Pipelines Agent.

When you use a GitHub-hosted machine, machine maintenance and upgrades are taken care of for you. You can run workflows directly on the virtual machine or in a Docker container.

GitHub hosts virtual machines with Linux, macOS, and Windows environments. Each job in a workflow executes in a fresh instance of the virtual environment. All steps in the job execute in the same instance of the virtual environment, allowing the actions in that job to share information using the filesystem.

You can specify the virtual environment for each job in a workflow. You can configure each job to run in different virtual environments or run all jobs in the same environment.

Supported virtual environments

GitHub provides several virtual environments. For a list of supported software, tools, and packages in each virtual environment, see "Software in virtual environments for GitHub Actions."

Virtual environment YAML workflow label
Windows Server 2019 windows-latest or windows-2019
Windows Server 2016 R2 windows-2016
Ubuntu 18.04 ubuntu-latest or ubuntu-18.04
Ubuntu 16.04 ubuntu-16.04
macOS X Mojave 10.14 macOS-latest or macOS-10.14

Filesystems on GitHub-hosted machines

GitHub creates directories for actions to use. Actions that run in Docker containers have static directories under the /github path. The GitHub-specific paths on virtual machines that run JavaScript and shell script actions are not static. GitHub provides environment variables that you can use to construct file paths for the home, workspace, and workflow directories used by GitHub Actions. For a list of the environment variables GitHub creates for each action, see "Default environment variables."

Docker container filesystem

We strongly recommend using the default environment variables to construct file paths in Docker containers.

GitHub reserves the /github path prefix and creates three directories for actions.

Environment variables

GitHub sets default environment variables available to every step in a workflow run. Additional environment variables are set in the workflow file. An action can create, read, and modify environment variables.

You can define environment variables for a step in a workflow file using the jobs.<job_id>.steps.env keyword. For more information, see "Workflow syntax for GitHub."

GitHub converts environment variables names to upper case. For example, if you set the variables first_name, middle_name, and last_name for a step in your workflow, you could read the FIRST_NAME, MIDDLE_NAME, and LAST_NAME environment variables.

steps:
- name: Hello world
  run: echo Hello world ${FIRST_NAME} ${MIDDLE_NAME} ${LAST_NAME}!
  env:
    first_name: Mona
    middle_name: The
    last_name: Octocat

Default environment variables

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

Environment variable Description
HOME The path to the GitHub home directory used to store user data. For example, /github/home.
GITHUB_WORKFLOW The name of the workflow.
GITHUB_ACTION The name of the action.
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. The workspace directory contains a subdirectory with a copy of your repository. For example, /github/workspace.
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 forked repositories. The branch of the head repository.
GITHUB_BASE_REF Only set for forked repositories. The branch of the base repository.

Naming conventions

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.

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.

Creating and using secrets (encrypted variables)

Secrets are encrypted environment variables created in a repository and can only be used by GitHub Actions. A secret is available to any action that includes it in the workflow file.

The name cannot include any spaces.

  1. On GitHub, navigate to the main page of the repository.

  2. Under your repository name, click Settings.

    Repository settings button

  3. In the left sidebar, click Secrets.

  4. Type a name for your secret in the "Name" input box.

  5. Type the value for your secret.

  6. Click Add secret.

To pass a secret to an action, set the secret as an input or environment variable in your workflow. Review the action's README file to learn about which inputs and environment variables the action expects. For more information, see "Workflow syntax for GitHub Actions."

With the exception of GITHUB_TOKEN, secrets are not passed to the runner when a workflow is triggered from a forked repository.

steps:
- name: Hello world action
  with: # Set the secret as an input
    super_secret: ${{ secrets.SuperSecret }}
  env: # Or as an environment variable
    super_secret: ${{ secrets.SuperSecret }}

GITHUB_TOKEN secret

The GITHUB_TOKEN secret is a GitHub App installation token scoped to a repository. GitHub creates the GITHUB_TOKEN secret for you by default, but you must include it in your workflow file in order for actions to use it. You can use the GITHUB_TOKEN secret to make authenticated GitHub API calls on behalf of an action.

Create an environment variable for each action in your workflow file that needs access to the GITHUB_TOKEN secret:

steps:
- name: My first action
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- name: My second action
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Token permissions

For information about the API endpoints GitHub Apps can access with each permission, see "GitHub App Permissions" in the GitHub Developer documentation.

Permission Access type Access by forked repos
checks read/write read
contents read/write read
deployments read/write read
issues read/write read
metadata read read
packages read/write read
pages read/write read
pull requests read/write read
repository hooks read/write read
repository projects read/write read
statuses read/write read
vulnerability alerts read read

Exit codes and statuses

You can use exit codes to provide an action's status. GitHub uses the exit code to set the GitHub Action's check run status, which can be success or failure.

Exit status Check run status Description
0 success The action completed successfully and other tasks that depends on it can begin.
Nonzero value failure Any other exit code indicates the action failed. When an action fails, all concurrent actions are canceled and future actions are skipped. The check run and check suite both get a failure status.

For more information about the Checks API, see "Checks" in the GitHub Developer documentation.

Ask a human

Can't find what you're looking for?

Contact us