Introduction
Well, let's provide some insight into how contextual information is accessed in GitHub Actions workflows. This is going to give us an idea of the many contexts at our disposal, which will optimize how we manage workflow runs, jobs, and steps.
Steps we will cover in this article:
What is the context on GitHub?
Contexts in GitHub Actions allow us to fetch details concerning the workflow runs, including variables, environment settings, jobs details, and so on. We will be able to access contexts through expressions like ${{ <context> }} that enable us to work with properties from various stages of the workflow.
We would instead consider looking at:
- Context: GitHub event data specific to, but not limited to, branch pull requests (github.ref).
- ENV context - these are Variables that had been defined at Workflow, Job or Step levels.
- Job and step contexts: Data specific either to the executing job or to the steps running in the context of the executing job.
- Secrets: The usual application is to store sensitive information, such as tokens that will be utilized during running time.
- Matrix and strategy contexts: This is quite useful when a matrix job running variant workflows, each based on changes in file parameters.
Practical Usage
Common consumption would be things like what branch is firing off the workflow via ${{ github.ref }}, and using that inside of conditional expressions to determine if certain jobs should run or not. Other common usage is to access the secrets context in order to securely pass authentication tokens within a job and not expose sensitive information. Another option is to print the context values into logs for debugging purposes by converting objects to JSON with ${{ toJson(<context>) }}. That would be helpful in case of the investigation of issues during workflow execution.
Branch-based Conditional Job Execution
In this example, the workflow will trigger a deployment to the production server only if the push is on the main branch.
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"
Matrix Job Example
The following example uses matrix jobs to run the same CI for multiple Node.js versions and operating systems:
name: Test matrix
on: push
jobs:
build:
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [ubuntu-latest, windows-latest]
node: [14, 16]
steps:
- uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node }}
- name: Output node version
run: node --version
Printing Context Information for Debugging
This will dump the GitHub context, job context, and runner context into the log files for debugging:
name: Context testing
on: push
jobs:
dump_contexts_to_log:
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 runner context
env:
RUNNER_CONTEXT: ${{ toJson(runner) }}
run: echo "$RUNNER_CONTEXT"
Conclusion
Knowing how to utilize the various contexts available within a workflow for our purposes can make our lives much easier when it comes to scaling and maintaining our CI/CD pipelines. With the use of expressions based upon the different contexts, we can DRY up configurations for jobs such that our workflows reduce the redundancy of our workflows and lock them down against potential attacks by becoming careful with untrusted inputs.