Github Actions: If Statement for Matrix Value
Posted by Miguel Lopez on Sat 11 February 2023 in automation
Technical Stack: Github Actions
Read: 2 minutes
Prerequisites
- Github
- Github Actions
Introduction
Github Actions is a continuous integration and continuous delivery (CI/CD) platform that allows you to automate your build, test, and deployment pipeline. Read More Here.
Matrix Jobs lets you use variables in a single job definition to automatically create multiple job runs that are based on the combinations of the variables. For example, you can use a matrix strategy to test your code in multiple versions of a language or on multiple operating systems. Source
After reading this, your will understand:
- How Matrix Jobs run in Github Actions
- How to conditionally run a block given a specific matrix value
Given This Matrix Strategy..
Github Actions allows you to pass an array of objects to define matrix jobs. This allows you to access the variables
at matrix.platforms.os
or matrix.platforms.os_version
.
jobs:
create-image:
name: 'Create Base Images'
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
platforms: [
{ os: "ubuntu", os_version: "16.04", npm_version: 12, ruby: true },
{ os: "ubuntu", os_version: "18.04", npm_version: 16 },
{ os: "ubuntu", os_version: "20.04", npm_version: 16 }
]
If Statement - Matrix Value Null / Boolean Check
For null/boolean comparisons, do not compare your matrix value to any strings, numbers or booleans. Use the format if: matrix.platforms.ruby
for two reasons:
- This format performs a null check on the
ruby
value. Jobs could choose to omit thematrix.platforms.ruby
and this job will be skipped. - This format also peforms a boolean check if
ruby
contains a boolean value.
- if: matrix.platforms.ruby
name: Add Ruby Dependencies
run: echo "Install Ruby specific packages."
Full List of Github Action Operators
If Statement - Matrix Value String / Number Comparison
For string values, be sure to enclose your value in single quotes ' '
. Enclosing them in double quotes "
will throw an error.
- if: matrix.platforms.os_version == '16.04'
name: Add Ubuntu Packages (legacy)
run: echo "Install Ubuntu 16.04 specific packages."
- if: matrix.platforms.npm_version == 16
name: Add NPM Dependencies
run: echo "Install NPM dependencies."
Full List of Github Action Operators
Full Github Action
name: 'Create Artifacts'
on:
pull_request:
jobs:
create-images:
name: 'Create Base Images'
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
platforms: [
{os: "ubuntu", os_version: "16.04", legacy: true},
{os: "ubuntu", os_version: "18.04"},
{os: "ubuntu", os_version: "20.04"}
]
steps:
- if: matrix.platforms.os_version == '16.04'
name: Add Ubuntu Packages (legacy)
run: echo "Install Ubuntu 16.04 specific packages."
- name: Add Ubuntu Packages
run: echo "Install Ubuntu packages."
Using A Different Matrix Strategy
Traditional Matrix Jobs are setup like this:
jobs:
example_matrix:
strategy:
matrix:
os_version: ['16.04', '18.04', '20.04']
os: ['ubuntu']
You could still use if statements in the following way:
if: matrix.os_version == '18.04'
Includes and Excludes
Github Actions has support to skip an entire matrix value using include
or exclude
. The following configuraiton
would skip the { "os": "ubuntu", "os_version": "16.04" }
job.
exclude:
- os_version: '16.04'
Using exclude
or include
skips the entire workflow. For this reason, it's sometimes better to use if
statements in order to accomplish your workflow.