Note: GitHub Actions is currently in beta for GitHub AE.
About contexts and expressions
You can use expressions to programmatically set variables in workflow files and access contexts. An expression can be any combination of literal values, references to a context, or functions. You can combine literals, context references, and functions using operators.
Expressions are commonly used with the conditional if
keyword in a workflow file to determine whether a step should run. When an if
conditional is true
, the step will run.
You need to use specific syntax to tell GitHub to evaluate an expression rather than treat it as a string.
${{ <expression> }}
When you use expressions in an if
conditional, you may omit the expression syntax (${{ }}
) because GitHub automatically evaluates the if
conditional as an expression, unless the expression contains any operators. If the expression contains any operators, the expression must be contained within ${{ }}
to explicitly mark it for evaluation. For more information about if
conditionals, see "Workflow syntax for GitHub Actions."
Example expression in an if
conditional
steps:
- uses: actions/hello-world-javascript-action@v1.1
if: ${{ <expression> }}
Example setting an environment variable
env:
my_env_var: ${{ <expression> }}
Contexts
Contexts are a way to access information about workflow runs, runner environments, jobs, and steps. Contexts use the expression syntax.
${{ <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 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.
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.
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. For example, the first script you run will have the name run1 , and the second script will be named run2 . 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 run steps 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 a pull_request . |
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 a pull_request . |
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 in 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.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.os | string | The operating system of the runner executing the job. Possible values are Linux , Windows , or macOS . |
runner.temp | string | The path of the temporary directory for the runner. This directory is guaranteed to be empty at the start of each job, even on self-hosted runners. |
runner.tool_cache | string | For instructions on how to make sure your AE hosted runner has the required software installed, see "Creating custom images." |
|
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"
Literals
As part of an expression, you can use boolean
, null
, number
, or string
data types. Boolean literals are not case sensitive, so you can use true
or True
.
Data type | Literal value |
---|---|
boolean | true or false |
null | null |
number | Any number format supported by JSON. |
string | You must use single quotes. Escape literal single-quotes with a single quote. |
Example
env:
myNull: ${{ null }}
myBoolean: ${{ false }}
myIntegerNumber: ${{ 711 }}
myFloatNumber: ${{ -9.2 }}
myHexNumber: ${{ 0xff }}
myExponentialNumber: ${{ -2.99-e2 }}
myString: ${{ 'Mona the Octocat' }}
myEscapedString: ${{ 'It''s open source!' }}
Operators
Operator | Description |
---|---|
( ) | Logical grouping |
[ ] | Index |
. | Property dereference |
! | Not |
< | Less than |
<= | Less than or equal |
> | Greater than |
>= | Greater than or equal |
== | Equal |
!= | Not equal |
&& | And |
|| | Or |
GitHub performs loose equality comparisons.
-
If the types do not match, GitHub coerces the type to a number. GitHub casts data types to a number using these conversions:
Type Result Null 0
Boolean true
returns1
false
returns0
String Parsed from any legal JSON number format, otherwise NaN
.
Note: empty string returns0
.Array NaN
Object NaN
-
A comparison of one
NaN
to anotherNaN
does not result intrue
. For more information, see the "NaN Mozilla docs." -
GitHub ignores case when comparing strings.
-
Objects and arrays are only considered equal when they are the same instance.
Functions
GitHub offers a set of built-in functions that you can use in expressions. Some functions cast values to a string to perform comparisons. GitHub casts data types to a string using these conversions:
Type | Result |
---|---|
Null | '' |
Boolean | 'true' or 'false' |
Number | Decimal format, exponential for large numbers |
Array | Arrays are not converted to a string |
Object | Objects are not converted to a string |
contains
contains( search, item )
Returns true
if search
contains item
. If search
is an array, this function returns true
if the item
is an element in the array. If search
is a string, this function returns true
if the item
is a substring of search
. This function is not case sensitive. Casts values to a string.
Example using an array
contains(github.event.issue.labels.*.name, 'bug')
Example using a string
contains('Hello world', 'llo')
returns true
startsWith
startsWith( searchString, searchValue )
Returns true
when searchString
starts with searchValue
. This function is not case sensitive. Casts values to a string.
Example
startsWith('Hello world', 'He')
returns true
endsWith
endsWith( searchString, searchValue )
Returns true
if searchString
ends with searchValue
. This function is not case sensitive. Casts values to a string.
Example
endsWith('Hello world', 'ld')
returns true
format
format( string, replaceValue0, replaceValue1, ..., replaceValueN)
Replaces values in the string
, with the variable replaceValueN
. Variables in the string
are specified using the {N}
syntax, where N
is an integer. You must specify at least one replaceValue
and string
. There is no maximum for the number of variables (replaceValueN
) you can use. Escape curly braces using double braces.
Example
Returns 'Hello Mona the Octocat'
format('Hello {0} {1} {2}', 'Mona', 'the', 'Octocat')
Example escaping braces
Returns '{Hello Mona the Octocat!}'
format('{{Hello {0} {1} {2}!}}', 'Mona', 'the', 'Octocat')
join
join( array, optionalSeparator )
The value for array
can be an array or a string. All values in array
are concatenated into a string. If you provide optionalSeparator
, it is inserted between the concatenated values. Otherwise, the default separator ,
is used. Casts values to a string.
Example
join(github.event.issue.labels.*.name, ', ')
may return 'bug, help wanted'
toJSON
toJSON(value)
Returns a pretty-print JSON representation of value
. You can use this function to debug the information provided in contexts.
Example
toJSON(job)
might return { "status": "Success" }
fromJSON
fromJSON(value)
Returns a JSON object or JSON data type for value
. You can use this function to provide a JSON object as an evaluated expression or to convert environment variables from a string.
Example returning a JSON object
This workflow sets a JSON matrix in one job, and passes it to the next job using an output and fromJSON
.
name: build
on: push
jobs:
job1:
runs-on: ubuntu-latest
outputs:
matrix: ${{ steps.set-matrix.outputs.matrix }}
steps:
- id: set-matrix
run: echo "::set-output name=matrix::{\"include\":[{\"project\":\"foo\",\"config\":\"Debug\"},{\"project\":\"bar\",\"config\":\"Release\"}]}"
job2:
needs: job1
runs-on: ubuntu-latest
strategy:
matrix: ${{fromJSON(needs.job1.outputs.matrix)}}
steps:
- run: build
Example returning a JSON data type
This workflow uses fromJSON
to convert environment variables from a string to a Boolean or integer.
name: print
on: push
env:
continue: true
time: 3
jobs:
job1:
runs-on: ubuntu-latest
steps:
- continue-on-error: ${{ fromJSON(env.continue) }}
timeout-minutes: ${{ fromJSON(env.time) }}
run: echo ...
hashFiles
hashFiles(path)
Returns a single hash for the set of files that matches the path
pattern. You can provide a single path
pattern or multiple path
patterns separated by commas. The path
is relative to the GITHUB_WORKSPACE
directory and can only include files inside of the GITHUB_WORKSPACE
. This function calculates an individual SHA-256 hash for each matched file, and then uses those hashes to calculate a final SHA-256 hash for the set of files. For more information about SHA-256, see "SHA-2."
You can use pattern matching characters to match file names. Pattern matching is case-insensitive on Windows. For more information about supported pattern matching characters, see "Workflow syntax for GitHub Actions."
Example with a single pattern
Matches any package-lock.json
file in the repository.
hashFiles('**/package-lock.json')
Example with multiple patterns
Creates a hash for any package-lock.json
and Gemfile.lock
files in the repository.
hashFiles('**/package-lock.json', '**/Gemfile.lock')
Job status check functions
You can use the following status check functions as expressions in if
conditionals. If your if
expression does not contain any of the status functions it will automatically result with success()
. For more information about if
conditionals, see "Workflow syntax for GitHub Actions."
success
Returns true
when none of the previous steps have failed or been canceled.
Example
steps:
...
- name: The job has succeeded
if: ${{ success() }}
always
Always returns true
, even when canceled. A job or step will not run when a critical failure prevents the task from running. For example, if getting sources failed.
Example
if: ${{ always() }}
cancelled
Returns true
if the workflow was canceled.
Example
if: ${{ cancelled() }}
failure
Returns true
when any previous step of a job fails.
Example
steps:
...
- name: The job has failed
if: ${{ failure() }}
Object filters
You can use the *
syntax to apply a filter and select matching items in a collection.
For example, consider an array of objects named fruits
.
[
{ "name": "apple", "quantity": 1 },
{ "name": "orange", "quantity": 2 },
{ "name": "pear", "quantity": 1 }
]
The filter fruits.*.name
returns the array [ "apple", "orange", "pear" ]