GitHub Actions Matrix Builds: Technical Guide

[inergyllc]

Select Topic Area

Show & Tell

Body

GitHub Actions Matrix Builds: Technical Guide

GitHub Actions is a powerful tool for automating software workflows, including CI/CD pipelines, testing, and deployments. One of its standout features is the ability to use matrix builds. This feature allows developers to run multiple job configurations in parallel, ensuring their code works across different environments and configurations. In this detailed article, we will explore what matrix builds are, their use cases, examples of large development shops using them, and provide an end-to-end real-world code example for a B2B Listing Directory code suite built on Azure.

What are GitHub Actions Matrix Builds?

Matrix builds in GitHub Actions enable you to run a job multiple times with different configurations. This is achieved by defining a matrix of parameters, such as different versions of a language runtime, operating systems, or other variables. Each combination of parameters will trigger a separate job, running in parallel. This is especially useful for testing code across a variety of environments to ensure compatibility and stability.

Use Cases for Matrix Builds

1. Cross-Platform Testing:
   • Ensure your software works on different operating systems like Windows, macOS, and Linux.
2. Multiple Language Versions:
   • Test your code against various versions of programming languages (e.g., Python 3.6, 3.7, 3.8).
3. Configuration Combinations:
   • Verify that different configurations (e.g., database versions, feature flags) do not break your application.
4. Dependency Versions:
   • Check compatibility with multiple versions of dependencies.

Examples of Large Development Shops Using Matrix Builds

Several large organizations and open-source projects use GitHub Actions matrix builds extensively:

• Microsoft: Uses matrix builds for testing cross-platform compatibility in many of its open-source projects.
• Facebook: Leverages matrix builds to test their JavaScript libraries and frameworks across different environments.
• Google: Utilizes matrix builds in projects like TensorFlow to ensure it runs smoothly on various operating systems and Python versions.
• Red Hat: Uses matrix builds for its open-source projects to validate compatibility across different distributions and versions of Linux.

Real-World Code Example: B2B Listing Directory Code Suite Built on Azure

Let's walk through an end-to-end example of setting up matrix builds for a B2B Listing Directory code suite built on Azure. This suite includes a web application and a backend API that need to be tested across different configurations.

Step 1: Setting Up the Repository

First, ensure your repository is set up with the necessary directories and files for GitHub Actions. Your repository should have the following structure:

├── .github
│   └── workflows
│       └── ci.yml
├── src
│   ├── frontend
│   └── backend
├── tests
│   ├── frontend_tests
│   └── backend_tests
└── README.md

Step 2: Define the Matrix in Your Workflow

Create the ci.yml file inside the .github/workflows directory. This file will define the matrix build configurations.

name: CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        node-version: [12.x, 14.x, 16.x]
    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Set up Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v2
        with:
          node-version: ${{ matrix.node-version }}

      - name: Install dependencies
        run: npm install

      - name: Run frontend tests
        run: npm run test:frontend
        working-directory: src/frontend

      - name: Run backend tests
        run: npm run test:backend
        working-directory: src/backend

Step 3: Setting Up the Application

Ensure your package.json files in both src/frontend and src/backend include the necessary scripts for running tests.

src/frontend/package.json:

{
  "scripts": {
    "test:frontend": "jest"
  }
}

src/backend/package.json:

{
  "scripts": {
    "test:backend": "jest"
  }
}

Step 4: Testing the Setup

Push your changes to GitHub and open a pull request. This should trigger the matrix build defined in your workflow file. You can monitor the progress and results in the "Actions" tab of your repository.

Expected Output Example

Workflow Triggered:
- Event: Push or Pull Request
- Workflow: CI

Job Matrix:
- Job Name: test
- Matrix Configurations:
  - os: ubuntu-latest, node-version: 12.x
  - os: ubuntu-latest, node-version: 14.x
  - os: ubuntu-latest, node-version: 16.x
  - os: windows-latest, node-version: 12.x
  - os: windows-latest, node-version: 14.x
  - os: windows-latest, node-version: 16.x
  - os: macos-latest, node-version: 12.x
  - os: macos-latest, node-version: 14.x
  - os: macos-latest, node-version: 16.x

Job Statuses:
- Running: Jobs will start running in parallel according to the matrix configurations.

Example Output for One Job:
- Job Configuration: os: ubuntu-latest, node-version: 14.x
- Steps:
  1. Checkout code:
     /usr/bin/git checkout --progress --force refs/remotes/pull/1/merge
     - Status: ✅ Success
  2. Set up Node.js 14.x:
     /usr/local/bin/nvm install 14
     Now using node v14.x (npm v6.x)
     - Status: ✅ Success
  3. Install dependencies:
     npm install
     added 123 packages from 567 contributors and audited 1234 packages in 12.34s
     - Status: ✅ Success
  4. Run frontend tests:
     npm run test:frontend
     > frontend@1.0.0 test:frontend /home/runner/work/B2B-Listing-Directory/src/frontend
     > jest
     PASS tests/example.test.js
     - Status: ✅ Success
  5. Run backend tests:
     npm run test:backend
     > backend@1.0.0 test:backend /home/runner/work/B2B-Listing-Directory/src/backend
     > jest
     PASS tests/api.test.js
     - Status: ✅ Success

Summary:
- Total Jobs: 9
- Successful Jobs: 9
- Failed Jobs: 0
- Duration: ~5 minutes

Benefits of Using Matrix Builds

1. Comprehensive Testing:
   • Matrix builds allow you to cover a wide range of environments, ensuring that your application is robust and reliable.
2. Parallel Execution:
   • By running jobs in parallel, matrix builds significantly reduce the total time required for testing.
3. Early Detection of Issues:
   • Catch compatibility issues and bugs early in the development cycle by testing against multiple configurations from the start.
4. Consistency:
   • Ensure that your application behaves consistently across different environments.

GitHub Actions matrix builds are a powerful feature for automating and streamlining the testing process across various environments. By leveraging matrix builds, you can ensure that your application is thoroughly tested, compatible, and reliable. This in-depth guide provides a comprehensive overview of matrix builds, their use cases, examples of their application in large development shops, and a real-world example of setting up matrix builds for a B2B Listing Directory code suite built on Azure. By following these steps, you can harness the full potential of GitHub Actions to enhance your CI/CD pipelines.