Build Matrix: Test All The Combinations
A build matrix automatically creates multiple jobs by combining different configurations. Use it to test your code across various operating systems, language versions, or dependencies without duplicating your workflow file.
WHY IT EXISTS Software needs to work in different environments. Manually creating a CI job for every combination of OS, language version, and architecture is tedious, error-prone, and hard to maintain. A build matrix automates this combinatorial explosion, ensuring comprehensive test coverage with minimal configuration.
THE MENTAL MODEL Think of a build matrix as a set of nested loops in your CI configuration. You define the variables for the loops (e.g., os = [ubuntu, macos], python-version = [3.9, 3.10]) and the CI system generates a job for every single combination (ubuntu/3.9, ubuntu/3.10, macos/3.9, macos/3.10).
HOW IT WORKS In your workflow file, you define a strategy with a matrix key. Inside the matrix, you define variables with arrays of values, like os: [ubuntu-latest, macos-latest] and node-version: [18, 20]. The CI runner will then create 2 x 2 = 4 jobs. In each job run, you can access the current values using context variables, like matrix.os and matrix.node-version, to set up the specific environment for that run.
WHEN TO USE IT Use a build matrix when you need to validate your code's compatibility across multiple dimensions. This is crucial for open-source libraries meant to be used by others, applications that support multiple operating systems, or projects that need to support several versions of a language or framework.
WHEN NOT TO USE IT Don't use a matrix for tasks that are completely independent and don't share a common structure, like test and deploy; those should be separate jobs. Be cautious with large matrices; a 3x3x3 matrix is 27 jobs. This can consume runner concurrency, take a long time, and incur high costs. Use include or exclude options to handle specific exceptions instead of adding another full dimension.
ONE CANONICAL EXAMPLE A common use case is testing a Node.js library. You would set up a matrix with os: [ubuntu-latest, windows-latest] and node-version: [18, 20]. This generates four jobs to ensure your library works on both major OS platforms and with both the current and long-term support (LTS) versions of Node.js, catching platform-specific bugs early.
Read the original → docs.github.com
Get five bites like this every day.
Tezvyn delivers a daily feed of 60-second tech bites with quizzes to lock in what you learn.