Understanding contexts in GitHub Actions

Kenny DuMez
Kenny DuMez
Graphite software engineer

Contexts in GitHub Actions are a set of variables that contain information about the workflow run, which can be used dynamically to manage the execution environment, and workflow configurations.. This guide will explore the different types of contexts available in GitHub Actions and how they can be utilized to help manage your workflows.

Contexts provide a way to access information about the runner environment, the event that triggered the workflow, secrets, and other data. These contexts are accessed using the expression syntax ${{ <context> }}.

Here are the primary contexts provided by GitHub Actions:

  1. github context: Contains information related to the event that triggered the workflow, such as the event type, the commit SHA, branch name, repository details, and more.
  2. env context: Represents environment variables that are available to the runtime environment of the runner.
  3. secrets context: Used to access repository secrets that are not logged or exposed to GitHub Actions logs.
  4. job context: Contains details about the current job, including its status.
  5. steps context: Provides outputs and other data from steps within the same job.
  6. runner context: Contains information about the runner that executes the job, such as the operating system and IP address.
  7. matrix context: Contains the specific matrix values for a job instance when using a strategy matrix.
  8. needs context: Allows jobs to access outputs from previous jobs that they depend on.

The github context contains information about the GitHub environment, such as the event that triggered the workflow, repository details, and workflow execution details. This context is often used to conditionally execute steps based on the type of event or to retrieve information about the commit.

Terminal
name: Example workflow using github context
on: [push, pull_request]
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Check out code
uses: actions/checkout@v2
- name: Print GitHub context
run: echo "The event that triggered this workflow is ${{ github.event_name }}."
  • This workflow activates on push and pull requests and simply prints out the type of event that triggered it.
  • github.event_name: Retrieves the name of the event that triggered the workflow (e.g., push or pull_request).

The env context allows you to access environment variables defined at various scopes within your workflow, such as at the workflow, job, or step level.

Terminal
name: Example workflow using env context
on: push
jobs:
build:
runs-on: ubuntu-latest
env:
MY_VAR: 'Hello World'
steps:
- name: Print environment variable
run: echo "The value of MY_VAR is $MY_VAR."
  • env: Defines the environment variable MY_VAR.
  • MY_VAR: This is an example of an environment variable set at the job level.
  • The script echoes the value of MY_VAR which is accessible using $MY_VAR in a Linux runner.

The secrets context is used to securely access repository secrets within a workflow. Secrets are not logged or exposed in GitHub Actions logs, keeping them secure.

Terminal
name: Example workflow using secrets context
on: push
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Use secret in environment variable
env:
MY_SECRET: ${{ secrets.MY_SECRET }}
run: echo "Using a secret in the workflow."
  • secrets.MY_SECRET: Accesses a secret named MY_SECRET stored in the repository's settings.
  • This example doesn't actually print the secret to logs, preserving security.

The job context contains details about the current job, including its status.

Terminal
name: Example workflow using job context
on: push
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Print job status
run: echo "The job status is ${{ job.status }}."
  • job.status: Provides the current status of the job. It's particularly useful for steps that might need to react conditionally depending on whether previous steps in the job succeeded or failed.

The steps context allows you to access outputs and other details from previous steps within the same job.

Terminal
name: Example workflow using steps context
on: push
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Set output
id: step1
run: echo "::set-output name=my_output::some value"
- name: Use output from previous step
run: echo "The output from step1 is ${{ steps.step1.outputs.my_output }}."
  • steps.step1.outputs.my_output: Retrieves the output named my_output from a step with ID step1.

The runner context provides information about the environment where the job is running, such as the operating system.

Terminal
name: Example workflow using runner context
on: push
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Print runner information
run: echo "The runner's OS is ${{ runner.os }}."
  • runner.os: Displays the operating system of the runner executing the job.

The matrix context is relevant when using a matrix strategy to run multiple versions of a job in parallel.

It provides details about the underlying matrix being used.

Terminal
name: Matrix strategy example
on: push
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
node-version: [12.x, 14.x, 16.x]
steps:
- name: Setup Node.js
uses: actions/setup-node@v2
with:
node-version: ${{ matrix.node-version }}
- name: Print strategy details
run: echo "Running with Node.js version ${{ matrix.node-version }} using a matrix strategy."
  • matrix.node-version: Accesses the Node.js version from the matrix strategy.

The needs context allows jobs to access outputs from previous jobs that they depend on, enabling complex workflows where jobs are interconnected based on their outputs.

Example:

Terminal
name: Example workflow using needs context
on: push
jobs:
job1:
runs-on: ubuntu-latest
outputs:
output1: "Data from job1"
steps:
- name: Set job output
run: echo "job1 completed"
job2:
needs: job1
runs-on: ubuntu-latest
steps:
- name: Use output from job1
run: echo "Received from job1: ${{ needs.job1.outputs.output1 }}"

Explanation:

  • needs.job1.outputs.output1: Accesses an output from job1 in job2, demonstrating how to chain jobs based on their outputs.

For further information see the official GitHub docs.

Give your PR workflow
an upgrade today

Stack easier | Ship smaller | Review quicker

Or install our CLI.
Product Screenshot 1
Product Screenshot 2