Note: GitHub Actions was available for GitHub Enterprise Server 2.22 as a limited beta. The beta has ended. GitHub Actions is now generally available in GitHub Enterprise Server 3.0 or later. For more information, see the GitHub Enterprise Server 3.0 release notes.
- For more information about upgrading to GitHub Enterprise Server 3.0 or later, see "Upgrading GitHub Enterprise Server."
- For more information about configuring GitHub Actions after you upgrade, see the documentation for GitHub Enterprise Server 3.0.
Note: GitHub-hosted runners are not currently supported on GitHub Enterprise Server. You can see more information about planned future support on the GitHub public roadmap.
About contexts
Warning: When creating workflows and actions, you should always consider whether your code might execute untrusted input from possible attackers. Certain contexts should be treated as untrusted input, as an attacker could insert their own malicious content. For more information, see "Understanding the risk of script injections."
Contexts are a way to access information about workflow runs, runner environments, jobs, and steps. Contexts use the expression syntax. For more information, see "Expressions."
${{ <context> }}
Context name | Type | Description |
---|---|---|
github | object | Information about the workflow run. For more information, see github context. |
env | object | Contains environment variables set in a workflow, job, or step. For more information, see env context. |
job | object | Information about the currently executing job. For more information, see job context. |
steps | object | Information about the steps that have been run in this job. For more information, see steps context. |
runner | object | Information about the runner that is running the current job. For more information, see runner context. |
secrets | object | Enables access to secrets. For more information about secrets, see "Creating and using encrypted secrets." |
strategy | object | Enables access to the configured strategy parameters and information about the current job. Strategy parameters include fail-fast , job-index , job-total , and max-parallel . |
matrix | object | Enables access to the matrix parameters you configured for the current job. For example, if you configure a matrix build with the os and node versions, the matrix context object includes the os and node versions of the current job. |
needs | object | Enables access to the outputs of all jobs that are defined as a dependency of the current job. For more information, see needs context. |
As part of an expression, you may access context information using one of two syntaxes.
- Index syntax:
github['sha']
- Property dereference syntax:
github.sha
In order to use property dereference syntax, the property name must:
- start with
a-Z
or_
. - be followed by
a-Z
0-9
-
or_
.
Determining when to use 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 asrunner.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.
github
context
The github
context contains information about the workflow run and the event that triggered the run. You can read most of the github
context data in environment variables. For more information about environment variables, see "Using environment variables."
Warning: When using the whole github
context, be mindful that it includes sensitive information such as github.token
. GitHub masks secrets when they are printed to the console, but you should be cautious when exporting or printing the context.
Warning: When creating workflows and actions, you should always consider whether your code might execute untrusted input from possible attackers. Certain contexts should be treated as untrusted input, as an attacker could insert their own malicious content. For more information, see "Understanding the risk of script injections."
Property name | Type | Description |
---|---|---|
github | object | The top-level context available during any job or step in a workflow. |
github.action | string | The name of the action currently running. GitHub removes special characters or uses the name __run when the current step runs a script. If you use the same action more than once in the same job, the name will include a suffix with the sequence number with underscore before it. For example, the first script you run will have the name __run , and the second script will be named __run_2 . Similarly, the second invocation of actions/checkout will be actionscheckout2 . |
github.action_path | string | The path where your action is located. You can use this path to easily access files located in the same repository as your action. This attribute is only supported in composite actions. |
github.actor | string | The login of the user that initiated the workflow run. |
github.base_ref | string | The base_ref or target branch of the pull request in a workflow run. This property is only available when the event that triggers a workflow run is either pull_request or pull_request_target . |
github.event | object | The full event webhook payload. For more information, see "Events that trigger workflows." You can access individual properties of the event using this context. |
github.event_name | string | The name of the event that triggered the workflow run. |
github.event_path | string | The path to the full event webhook payload on the runner. |
github.head_ref | string | The head_ref or source branch of the pull request in a workflow run. This property is only available when the event that triggers a workflow run is either pull_request or pull_request_target . |
github.job | string | The job_id of the current job. |
github.ref | string | The branch or tag ref that triggered the workflow run. For branches this is the format refs/heads/<branch_name> , and for tags it is refs/tags/<tag_name> . |
github.repository | string | The owner and repository name. For example, Codertocat/Hello-World . |
github.repository_owner | string | The repository owner's name. For example, Codertocat . |
github.run_id | string | A unique number for each run within a repository. This number does not change if you re-run the workflow run. |
github.run_number | string | 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.run_attempt | string | A unique number for each attempt of a particular workflow run in a repository. This number begins at 1 for the workflow run's first attempt, and increments with each re-run. |
github.server_url | string | Returns the URL of the GitHub server. For example: https://github.com . |
github.sha | string | The commit SHA that triggered the workflow run. |
github.token | string | A token to authenticate on behalf of the GitHub App installed on your repository. This is functionally equivalent to the GITHUB_TOKEN secret. For more information, see "Authenticating with the GITHUB_TOKEN." |
github.workflow | string | The name of the workflow. If the workflow file doesn't specify a name , the value of this property is the full path of the workflow file in the repository. |
github.workspace | string | The default working directory for steps and the default location of your repository when using the checkout action. |
env
context
The env
context contains environment variables that have been set in a workflow, job, or step. For more information about setting environment variables in your workflow, see "Workflow syntax for GitHub Actions."
The env
context syntax allows you to use the value of an environment variable in your workflow file. You can use the env
context in the value of any key in a step except for the id
and uses
keys. For more information on the step syntax, see "Workflow syntax for GitHub Actions."
If you want to use the value of an environment variable inside a runner, use the runner operating system's normal method for reading environment variables.
Property name | Type | Description |
---|---|---|
env | object | This context changes for each step in a job. You can access this context from any step in a job. |
env.<env_name> | string | The value of a specific environment variable. |
job
context
The job
context contains information about the currently running job.
Property name | Type | Description |
---|---|---|
job | object | This context changes for each job in a workflow run. You can access this context from any step in a job. |
job.container | object | Information about the job's container. For more information about containers, see "Workflow syntax for GitHub Actions." |
job.container.id | string | The id of the container. |
job.container.network | string | The id of the container network. The runner creates the network used by all containers in a job. |
job.services | object | The service containers created for a job. For more information about service containers, see "Workflow syntax for GitHub Actions." |
job.services.<service id>.id | string | The id of the service container. |
job.services.<service id>.network | string | The id of the service container network. The runner creates the network used by all containers in a job. |
job.services.<service id>.ports | object | The exposed ports of the service container. |
job.status | string | The current status of the job. Possible values are success , failure , or cancelled . |
steps
context
The steps
context contains information about the steps in the current job that have already run.
Property name | Type | Description |
---|---|---|
steps | object | This context changes for each step in a job. You can access this context from any step in a job. |
steps.<step id>.outputs | object | The set of outputs defined for the step. For more information, see "Metadata syntax for GitHub Actions." |
steps.<step id>.conclusion | string | The result of a completed step after continue-on-error is applied. Possible values are success , failure , cancelled , or skipped . When a continue-on-error step fails, the outcome is failure , but the final conclusion is success . |
steps.<step id>.outcome | string | The result of a completed step before continue-on-error is applied. Possible values are success , failure , cancelled , or skipped . When a continue-on-error step fails, the outcome is failure , but the final conclusion is success . |
steps.<step id>.outputs.<output name> | string | The value of a specific output. |
runner
context
The runner
context contains information about the runner that is executing the current job.
Property name | Type | Description |
---|---|---|
runner.name | string | The name of the runner executing the job. |
runner.os | string | The operating system of the runner executing the job. Possible values are Linux , Windows , or macOS . |
runner.temp | string | 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 | string | The path to the directory containing preinstalled tools for GitHub-hosted runners. For more information, see "Specifications for GitHub-hosted runners". |
needs
context
The needs
context contains outputs from all jobs that are defined as a dependency of the current job. For more information on defining job dependencies, see "Workflow syntax for GitHub Actions."
Property name | Type | Description |
---|---|---|
needs.<job id> | object | A single job that the current job depends on. |
needs.<job id>.outputs | object | The set of outputs of a job that the current job depends on. |
needs.<job id>.outputs.<output name> | string | The value of a specific output for a job that the current job depends on. |
needs.<job id>.result | string | The result of a job that the current job depends on. Possible values are success , failure , cancelled , or skipped . |
Example printing context information to the log file
To inspect the information that is accessible in each context, you can use this workflow file example.
Warning: When using the whole github
context, be mindful that it includes sensitive information such as github.token
. GitHub masks secrets when they are printed to the console, but you should be cautious when exporting or printing the context.
.github/workflows/main.yml
on: push
jobs:
one:
runs-on: ubuntu-latest
steps:
- name: Dump GitHub context
env:
GITHUB_CONTEXT: ${{ toJSON(github) }}
run: echo "$GITHUB_CONTEXT"
- name: Dump job context
env:
JOB_CONTEXT: ${{ toJSON(job) }}
run: echo "$JOB_CONTEXT"
- name: Dump steps context
env:
STEPS_CONTEXT: ${{ toJSON(steps) }}
run: echo "$STEPS_CONTEXT"
- name: Dump runner context
env:
RUNNER_CONTEXT: ${{ toJSON(runner) }}
run: echo "$RUNNER_CONTEXT"
- name: Dump strategy context
env:
STRATEGY_CONTEXT: ${{ toJSON(strategy) }}
run: echo "$STRATEGY_CONTEXT"
- name: Dump matrix context
env:
MATRIX_CONTEXT: ${{ toJSON(matrix) }}
run: echo "$MATRIX_CONTEXT"
Context availability
Different contexts are available throughout a workflow run. For example, the secrets
context may only be used at certain places within a job.
In addition, some functions may only be used in certain places. For example, the hashFiles
function is not available everywhere.
The following table indicates where each context and special function can be used within a workflow. Unless listed below, a function can be used anywhere.
Path | Context | Special functions |
---|---|---|
concurrency | github | |
env | github, secrets | |
jobs.<job_id>.concurrency | github, needs, strategy, matrix | |
jobs.<job_id>.container | github, needs, strategy, matrix | |
jobs.<job_id>.container.credentials | github, needs, strategy, matrix, env, secrets | |
jobs.<job_id>.container.env.<env_id> | github, needs, strategy, matrix, job, runner, env, secrets | |
jobs.<job_id>.continue-on-error | github, needs, strategy, matrix | |
jobs.<job_id>.defaults.run | github, needs, strategy, matrix, env | |
jobs.<job_id>.env | github, needs, strategy, matrix, secrets | |
jobs.<job_id>.environment | github, needs, strategy, matrix | |
jobs.<job_id>.environment.url | github, needs, strategy, matrix, job, runner, env, steps | |
jobs.<job_id>.if | github, needs | always, cancelled, success, failure |
jobs.<job_id>.name | github, needs, strategy, matrix | |
jobs.<job_id>.outputs.<output_id> | github, needs, strategy, matrix, job, runner, env, secrets, steps | |
jobs.<job_id>.runs-on | github, needs, strategy, matrix | |
jobs.<job_id>.services | github, needs, strategy, matrix | |
jobs.<job_id>.services.<service_id>.credentials | github, needs, strategy, matrix, env, secrets | |
jobs.<job_id>.services.<service_id>.env.<env_id> | github, needs, strategy, matrix, job, runner, env, secrets | |
jobs.<job_id>.steps.continue-on-error | github, needs, strategy, matrix, job, runner, env, secrets, steps | hashFiles |
jobs.<job_id>.steps.env | github, needs, strategy, matrix, job, runner, env, secrets, steps | hashFiles |
jobs.<job_id>.steps.if | github, needs, strategy, matrix, job, runner, env, steps | always, cancelled, success, failure, hashFiles |
jobs.<job_id>.steps.name | github, needs, strategy, matrix, job, runner, env, secrets, steps | hashFiles |
jobs.<job_id>.steps.run | github, needs, strategy, matrix, job, runner, env, secrets, steps | hashFiles |
jobs.<job_id>.steps.timeout-minutes | github, needs, strategy, matrix, job, runner, env, secrets, steps | hashFiles |
jobs.<job_id>.steps.with | github, needs, strategy, matrix, job, runner, env, secrets, steps | hashFiles |
jobs.<job_id>.steps.working-directory | github, needs, strategy, matrix, job, runner, env, secrets, steps | hashFiles |
jobs.<job_id>.strategy | github, needs | |
jobs.<job_id>.timeout-minutes | github, needs, strategy, matrix |