Building a dynamic matrix for GitHub actions

In this article we’re going to be covering how to to use some python to generate a dynamic matrix for a GitHub workflow.

What is a GitHub matrix?

A matrix can be used in a GitHub workflow to run a set of steps multiple times with different input parameters, for example if you wanted to run your tests against multiple versions of your language of choice, you could use something similar to GitHub’s example from the below documentation

jobs:
  example_matrix:
    strategy:
      matrix:
        version: [10, 12, 14]
    steps:
      - uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.version }}

GitHub documentation: https://docs.github.com/en/actions/using-jobs/using-a-matrix-for-your-jobs

This works great if you have a statically defined list that you wish to iterate over every time the workflow runs, however, what happens if you have a changing list that requires different inputs depending on some external context — for example ephemeral testing environments, github repositories that require processing based on security findings etc.

I have setup a GitHub repository to demonstrate the power of dynamic matrix in GitHub actions, using a simple python script and a random number generator to generate a random number of jobs of random length.

GitHub repo: https://github.com/tjtharrison/demo-github-dynamic-matrix