Running complex matrix builds using variable substitution in GitHub Actions

Matrix workflows in GitHub Actions handle the variable substitution for you. You define a set of variables in the matrix keyword, and GitHub Actions takes over the expansion expansions of those variables for you.

In the open source Node world, maintainers need to keep their CI up to date with tests for multiple versions of Node.js. Matrix builds in GitHub Actions become powerful very quickly.

In the examples below, I want to test with four different node versions and three versions of Mongo, and two versions of Redis. To test these different combinations, that's 24 different configurations.

Instead of defining sixteen different jobs, or worse, having to set up 24 different machines on your kitchen table(s), I can just specify a matrix with three variables. If I specify a matrix in a job, I'll actually get sixteen jobs running with the different permutations:

name: Run test matrix

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [8.x, 10.x, 12.x, 14.x]
        mongodb-version: [4.0, 4.2, 4.4]
        redis-version: [4, 5]

    steps:
    - name: Git checkout
      uses: actions/checkout@v2

    - name: Use Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v1
      with:
        node-version: ${{ matrix.node-version }}

    - name: Start MongoDB v${{ matrix.mongodb-version }}
      uses: supercharge/mongodb-github-action@1.3.0
      with:
        mongodb-version: ${{ matrix.mongodb-version }}

    - name: Start Redis v${{ matrix.redis-version }}
      uses: supercharge/redis-github-action@1.1.0
      with:
        redis-version: ${{ matrix.redis-version }}

    - run: echo "done"

Each node eversion is running the latest minor version, i.e. 14.x will run 14.15.4

When you run this workflow, you can see quickly how it expands to 16 different jobs. On the left of the workflow run, you can see each of them. So that simple workflow expanded out very quickly.

When you open up the steps on one of the runs, you can see that indeed we were able to install our dependencies. If I open up the build I'm in fact running an environment with Node, MongoDB, and Redis.

To learn more about MongoDB replica sets checkout the supercharge/mongodb-github-action README.

This is part of my 28 days of Actions series. To get notified of more GitHub Action tips, follow the GitHub organization right here on Dev.

01:55

Skip pull request and push GitHub Action workflows with [skip ci]

Brian Douglas for GitHub ・ Feb 9 '21 ・ 1 min read

#devops #github #githubactions