Contexts and expression syntax for GitHub Actions

You can access context information and evaluate expressions in workflows and actions.

GitHub Actions is available with GitHub Free, GitHub Pro, GitHub Team, and GitHub Enterprise Cloud. For more information, see "GitHub's products."

In this article

About context 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 do not need to use the expression syntax ({{ }}) because GitHub automatically evaluates the if conditional as an expression. 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@master
    if: <expression>

Example setting an environment variable

env:
  my_env_var: ${{ <expression> }}

Contexts

Contexts are a way to access information about a workflow run, virtual environment, 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 string A step, job, or workflow environment variable.
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.
secrets object Enables access to secrets set in a repository. For more information about secrets, see "Virtual environments for GitHub Actions."
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.

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

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 "Virtual environments for GitHub Actions."

Property name Type Description
github object The top-level context available during any job or step in a workflow.
github.event object The full event webhook payload. For more information, see "Events that trigger workflows."
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.actor string The login of the user that initiated the workflow run.
github.repository string The owner and repository name. For example, Codertocat/Hello-World.
github.event_name string The name of the event that triggered the workflow run.
github.sha string The commit SHA that triggered the workflow run.
github.ref string The branch or tag ref that triggered the workflow run.
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.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.

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.status string The current status of the job. Possible values are success, failure, or cancelled.
job.container object Information about the job's container. For more information about containers, see "Workflow syntax for GitHub Actions."
job.container.network string The id of the container network. The runner creates the network used by all containers in a job.
job.container.id string The id of the container.
job.services object The service containers created for a job. For more information about service containers, see "Workflow syntax for GitHub Actions."
job.services.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>.id string The id of the service container.
job.services.<service id>.ports object The exposed ports of the container.

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>.outputs.<output name> string The value of a specific output.

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.

.github/workflows/main.yml

on: push

jobs:
  one:
    runs-on: ubuntu-16.04
    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 returns 1
    false returns 0
    String Parsed from any legal JSON number format, otherwise NaN.
    Note: empty string returns 0.
    Array NaN
    Object NaN
  • A comparison of one NaN to another NaN does not result in true. 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( searchString, searchValue )

Returns true if the searchString contains searchValue. If searchString is an array, this function returns true if the searchValue is an element in the array. This function is not case sensitive. Casts values to a string.

Example

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 useing 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( element, optionalElem )

The value for element can be an array or string. All values in element are concatenated into a string. If you provide optionalElem, the value is appended to the end of element. Casts values to a string.

Example using array

join(['Hello', 'Mona', 'the'], 'Octocat') returns 'Hello Mona the Octocat'

Example using string

join('Hello', 'world!') returns 'Hello world!'

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

hashFiles

hashFiles(path)

Returns a single hash for the set of files that matches the path pattern. 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

Matches any package-lock.json file in the repository.

hashFiles('**/package-lock.json')

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 the previous step of a job succeeds.

Example
steps:
  - name: my first step
    if: success()

always

Forces a conditional to evaluate as 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 the previous step of a job fails.

Example
steps:
  - name: my first step
    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" ]

Ask a human

Can't find what you're looking for?

Contact us