Contexts are a way to access information about workflow runs, variables, runner environments, jobs, and steps. Each context is an object that contains properties, which can be strings or other objects.

You can access contexts using the expression syntax. 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.

Contexts

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, visit Security hardening for GitHub Actions.”

The following table contains examples of contexts available in GitHub, it’s not a complete listing.

Determining when to use contexts

GitHub Actions include two collections of variables called default variables and contexts. These variables are intended for use at different points in the workflow:

• Default environment variables: These environment variables exist only on the runner that is executing your job.
• Contexts: You can use most contexts at any point in your workflow, including when default variables would be unavailable.

In the following example, the if statement checks the github.ref context to determine the current branch name. The if check is processed, 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 variable from the runner.

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"

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"

Contexts available in GitHub Actions

The following table contains the available top-level contexts, a brief description, and a link to more information on the object’s properties.

Expressions

You can use expressions to programmatically set environment 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 runs.

You need to use specific syntax, ${{ <expression> }}, to tell GitHub to evaluate an expression rather than treat it as a string. The exception to this rule is when you’re using expressions in an if clause, where they can usually be omitted ${{ and }}.

The following code sample shows setting an environment variable.

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

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

Literals

As part of an expression, you can use boolean, null, number, or string data types. In conditionals, falsy values (false, 0, -0, "", '', null) are coerced to false and truthy (true and other non-falsy values) are coerced to true. The following shows examples of implementing literals.

env:
  myNull: ${{ null }}
  myBoolean: ${{ false }}
  myIntegerNumber: ${{ 711 }}
  myFloatNumber: ${{ -9.2 }}
  myHexNumber: ${{ 0xff }}
  myExponentialNumber: ${{ -2.99e-2 }}
  myString: Mona the Octocat
  myStringInBraces: ${{ 'It''s open source!' }}

env:
  myNull: ${{ null }}
  myBoolean: ${{ false }}
  myIntegerNumber: ${{ 711 }}
  myFloatNumber: ${{ -9.2 }}
  myHexNumber: ${{ 0xff }}
  myExponentialNumber: ${{ -2.99e-2 }}
  myString: Mona the Octocat
  myStringInBraces: ${{ 'It''s open source!' }}

Operators

Operators play a crucial role in evaluating expressions. An expression can consist of literal values, references to contexts, or functions. Operators allow you to combine these elements to create more complex expressions. Here are some key operators:

• Logical Operators:
  • && (and): Combines two conditions, both of which must be true for the overall expression to evaluate as true.
  • || (or): Combines two conditions, and the expression evaluates as true if either condition is true.
  • ! (not): Negates a condition, flipping its truth value.
• Equality Operators:
  • == (equal): Compares two values for equality.
  • != (not equal): Checks if two values aren’t equal.
• Comparison Operators:
  • < (less than)
  • > (greater than)
  • <= (less than or equal to)
  • >= (greater than or equal to)

These operators allow you to create dynamic workflows by determining when specific steps should run based on conditions. Remember to use the correct syntax for expressions, such as $\{\{ <expression> \}\}$, to ensure proper evaluation.

For more information on operators, visit Operators.