Virtual environments for GitHub Actions

In this article

• About virtual environments
• Supported virtual environments
• Filesystems on GitHub-hosted machines
• Environment variables
• Creating and using secrets (encrypted variables)
• Exit codes and statuses

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."

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."

• home: Contains user-related data. For example, this directory could contain credentials from a login attempt. Use the HOME environment variable to access this directory.
• workspace: Actions execute in this directory. An action can modify the contents of this directory, which subsequent actions can access. Use the GITHUB_WORKSPACE environment variable to access this directory.
• workflow/event.json: The POST payload of the webhook event that triggered the workflow. GitHub rewrites this each time an action executes to isolate file content between actions. Use the GITHUB_EVENT_PATH environment variable to access this file.

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.

• /github/home
• /github/workspace - Note: GitHub Actions must be run by the default Docker user (root). Ensure your Dockerfile does not set the USER instruction, otherwise you will not be able to access GITHUB_WORKSPACE.
• /github/workflow

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.

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.

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.

   

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.

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.

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