Understanding contexts in GitHub Actions

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.

Understanding contexts in GitHub Actions

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

Types of contexts

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.

Examples of using contexts

1. github context

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.

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

2. env context

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.

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.

3. secrets context

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.

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.

4. job context

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

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.

5. steps context

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

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.

6. runner context

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

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.

7. matrix context

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.

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.

9. needs context

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:

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.