This action helps build more complex GitHub Actions build matrices.
Required Build matrix configuration.
A build matrix to use in your jobs.
Use this action in a job and use its output as your build matrix.
jobs:
setup-build-matrix:
runs-on: ubuntu-latest
steps:
- name: Build matrix
id: build-matrix
uses: jgiannuzzi/setup-build-matrix@v1
with:
config: |
matrix:
# Base matrix
os: [ubuntu-latest, windows-latest]
component: [backend, ui]
dotnet: [3.1.405, 5.0.102]
operations:
# Do a database-style outer join to merge the 2 node versions
# on matching component==ui keys.
- type: merge
match: [component]
matrix:
component: [ui]
node: [14.15.4, 15.6.0]
# Add an extra dotnet version just for ui on windows
- type: add
match: [os, component]
matrix:
os: [windows-latest]
component: [ui]
dotnet: [4.7.2]
outputs:
matrix: ${{ steps.build-matrix.outputs.matrix }}
build:
needs: setup-build-matrix
strategy:
matrix: ${{ fromJson(needs.setup-build-matrix.outputs.matrix) }}
runs-on: ${{ matrix.os }}
steps:
...The above workflow is equivalent to this:
jobs:
build:
strategy:
matrix:
include:
- os: ubuntu-latest
component: backend
dotnet: 3.1.405
- os: ubuntu-latest
component: backend
dotnet: 5.0.102
- os: ubuntu-latest
component: ui
dotnet: 3.1.405
node: 14.15.4
- os: ubuntu-latest
component: ui
dotnet: 3.1.405
node: 15.6.0
- os: ubuntu-latest
component: ui
dotnet: 5.0.102
node: 14.15.4
- os: ubuntu-latest
component: ui
dotnet: 5.0.102
node: 15.6.0
- os: windows-latest
component: backend
dotnet: 3.1.405
- os: windows-latest
component: backend
dotnet: 5.0.102
- os: windows-latest
component: ui
dotnet: 3.1.405
node: 14.15.4
- os: windows-latest
component: ui
dotnet: 3.1.405
node: 15.6.0
- os: windows-latest
component: ui
dotnet: 4.7.2
node: 14.15.4
- os: windows-latest
component: ui
dotnet: 4.7.2
node: 15.6.0
- os: windows-latest
component: ui
dotnet: 5.0.102
node: 14.15.4
- os: windows-latest
component: ui
dotnet: 5.0.102
node: 15.6.0
runs-on: ${{ matrix.os }}
steps:
...It can be helpful to visualize the operations that happened as actual matrices.
This is our initial matrix.
| os | component | dotnet |
|---|---|---|
| ubuntu-latest | backend | 3.1.405 |
| ubuntu-latest | backend | 5.0.102 |
| ubuntu-latest | ui | 3.1.405 |
| ubuntu-latest | ui | 5.0.102 |
| windows-latest | backend | 3.1.405 |
| windows-latest | backend | 5.0.102 |
| windows-latest | ui | 3.1.405 |
| windows-latest | ui | 5.0.102 |
We start by doing a merge with the following matrix on the component column.
| component | node |
|---|---|
| ui | 14.15.4 |
| ui | 15.6.0 |
This results in the following intermediate matrix.
Notice the new merged rows in bold that are replacing the previous ui rows.
| os | component | dotnet | node |
|---|---|---|---|
| ubuntu-latest | backend | 3.1.405 | |
| ubuntu-latest | backend | 5.0.102 | |
| ubuntu-latest | ui | 3.1.405 | 14.15.4 |
| ubuntu-latest | ui | 3.1.405 | 15.6.0 |
| ubuntu-latest | ui | 5.0.102 | 14.15.4 |
| ubuntu-latest | ui | 5.0.102 | 15.6.0 |
| windows-latest | backend | 3.1.405 | |
| windows-latest | backend | 5.0.102 | |
| windows-latest | ui | 3.1.405 | 14.15.4 |
| windows-latest | ui | 3.1.405 | 15.6.0 |
| windows-latest | ui | 5.0.102 | 14.15.4 |
| windows-latest | ui | 5.0.102 | 15.6.0 |
We then add the following matrix, matching on the os and component columns.
| os | component | dotnet |
|---|---|---|
| windows-latest | ui | 4.7.2 |
This results in the following final matrix. Notice the 2 new added rows in bold.
| os | component | dotnet | node |
|---|---|---|---|
| ubuntu-latest | backend | 3.1.405 | |
| ubuntu-latest | backend | 5.0.102 | |
| ubuntu-latest | ui | 3.1.405 | 14.15.4 |
| ubuntu-latest | ui | 3.1.405 | 15.6.0 |
| ubuntu-latest | ui | 5.0.102 | 14.15.4 |
| ubuntu-latest | ui | 5.0.102 | 15.6.0 |
| windows-latest | backend | 3.1.405 | |
| windows-latest | backend | 5.0.102 | |
| windows-latest | ui | 3.1.405 | 14.15.4 |
| windows-latest | ui | 3.1.405 | 15.6.0 |
| windows-latest | ui | 4.7.2 | 14.15.4 |
| windows-latest | ui | 4.7.2 | 15.6.0 |
| windows-latest | ui | 5.0.102 | 14.15.4 |
| windows-latest | ui | 5.0.102 | 15.6.0 |
Note that the rows that have no values for a column will not have that key set at all in their resulting matrix object.