Context and expression syntax for GitHub Actions

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

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

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.

job context

The job context contains information about the currently running job.

steps context

The steps context contains information about the steps in the current job that have already run.

runner context

The runner context contains information about the runner that is executing the current job.

|

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

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

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

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:

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