2.11 GitHub Advanced Workflows: Matrix Builds, Reusable Workflows, and Secrets

Level Up Your GitHub Actions: Matrix Builds, Reusable Workflows, and Secrets!

GitHub Actions are a powerful way to automate your development workflow, from testing your code to deploying your applications. But did you know you can make them even more powerful and efficient? In this post, we’ll explore three advanced features: Matrix Builds, Reusable Workflows, and Secrets. These will help you run more comprehensive tests, avoid repetitive code, and keep your sensitive information safe.

Let’s dive in!

1. Matrix Builds: Testing Across Multiple Configurations

Imagine you’re building a web application that needs to run on different operating systems (like Windows, macOS, and Linux) and with different versions of Node.js. Manually setting up separate workflows for each combination would be tedious, right?

That’s where Matrix Builds come in! A matrix build lets you define multiple configurations for your workflow and GitHub Actions will automatically run your jobs against each combination.

Think of it like this: You create a table (a matrix!) that specifies the different variations you want to test.

Example:

Let’s say you want to test your Node.js project with Node.js versions 16, 18, and 20, and on both Linux and Windows. Your workflow.yml file might look like this:

name: Node.js CI

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

jobs:
  build:
    runs-on: ubuntu-latest  # Base operating system
    strategy:
      matrix:
        node-version: [16, 18, 20]
        os: [ubuntu-latest, windows-latest]

    steps:
      - uses: actions/checkout@v3
      - name: Use Node.js ${{ matrix.node-version }} on ${{ matrix.os }}
        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}
      - run: npm install
      - run: npm run build --if-present
      - run: npm test

Explanation:

• strategy: matrix: This line tells GitHub Actions that we’re using a matrix build.
• node-version: [16, 18, 20]: This defines an array of Node.js versions to test against.
• os: [ubuntu-latest, windows-latest]: This defines the operating systems to test on.
• {{ matrix.node-version }} and {{ matrix.os }}: These are special variables that access the current values from the matrix for each job run.

What happens when you run this?

GitHub Actions will create six separate jobs:

1. Node.js 16 on Ubuntu
2. Node.js 16 on Windows
3. Node.js 18 on Ubuntu
4. Node.js 18 on Windows
5. Node.js 20 on Ubuntu
6. Node.js 20 on Windows

Each job will run independently, giving you comprehensive test coverage!

Benefits of Matrix Builds:

• Comprehensive Testing: Test across multiple configurations easily.
• Efficiency: Avoid manually duplicating workflows.
• Faster Feedback: Get results for all configurations simultaneously.

2. Reusable Workflows: Don’t Repeat Yourself!

Are you finding yourself copying and pasting the same blocks of YAML code across multiple workflows? Reusable Workflows are here to save the day! They allow you to define a workflow once and then call it from other workflows.

Think of it like creating a function in programming: You define the function once and then call it whenever you need to perform that specific task.

Example:

Let’s create a reusable workflow called deploy.yml that handles deploying your application to a staging environment:

# .github/workflows/deploy.yml
name: Deploy to Staging

on:
  workflow_call:
    inputs:
      environment:
        required: true
        type: string

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Deploy to ${{ inputs.environment }}
        run: |
          echo "Deploying to ${{ inputs.environment }} environment..."
          # Your deployment commands here

Explanation:

• on: workflow_call: This makes this workflow reusable.
• inputs: This defines the inputs that the calling workflow needs to provide. In this case, we’re requiring an environment input (e.g., “staging”).
• ${{ inputs.environment }}: This accesses the input value provided by the calling workflow.

Now, let’s create another workflow, build-and-deploy.yml, that calls the deploy.yml workflow:

# .github/workflows/build-and-deploy.yml
name: Build and Deploy

on:
  push:
    branches: [ "main" ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Build the application
        run: |
          echo "Building the application..."
          # Your build commands here

  deploy-staging:
    needs: build
    uses: ./.github/workflows/deploy.yml
    with:
      environment: staging

Explanation:

• uses: ./.github/workflows/deploy.yml: This tells the workflow to use the reusable workflow defined in deploy.yml.
• with: environment: staging: This provides the required environment input to the deploy.yml workflow.

Benefits of Reusable Workflows:

• Code Reusability: Avoid duplication and keep your workflows DRY (Don’t Repeat Yourself).
• Maintainability: Update the reusable workflow in one place, and all calling workflows will benefit.
• Simplified Workflows: Break down complex workflows into smaller, more manageable chunks.

3. Secrets: Protecting Sensitive Information

Your workflows might need to access sensitive information, such as API keys, passwords, or SSH keys. Never hardcode these directly into your workflow files! Instead, use GitHub Secrets.

GitHub Secrets are encrypted environment variables that you can securely store in your repository settings. You can then access these secrets within your workflows.

How to create a secret:

1. Go to your GitHub repository.
2. Click on “Settings”.
3. Click on “Secrets and variables” then “Actions”.
4. Click “New repository secret”.
5. Give your secret a name (e.g., API_KEY) and paste in its value.
6. Click “Add secret”.

How to use a secret in your workflow:

name: Use Secrets

on:
  push:
    branches: [ "main" ]

jobs:
  example:
    runs-on: ubuntu-latest
    steps:
      - name: Use the API key
        run: |
          echo "Using API key: ${{ secrets.API_KEY }}"
          # Use the API key in your script

Explanation:

• ${{ secrets.API_KEY }}: This accesses the secret named API_KEY that you stored in your repository settings.

Important Security Considerations:

• Never print secrets to the console (except for debugging purposes and then REMOVE the print statement).
• Be mindful of who has access to your repository’s settings.
• Consider using environment secrets instead of repository secrets when access control needs to be defined at the environment level

Benefits of Using Secrets:

• Security: Protect sensitive information from being exposed.
• Centralized Management: Manage all your secrets in one place.
• Easy Access: Access secrets easily within your workflows.

Conclusion

Matrix builds, reusable workflows, and secrets are powerful tools that can significantly improve your GitHub Actions workflows. By using them effectively, you can write more comprehensive tests, avoid repetitive code, and keep your sensitive information safe. Start experimenting with these features and take your GitHub Actions to the next level! Happy automating!