GitHub Actions: Map Key-Value Pairs in a Matrix

In GitHub Actions, a matrix is a great tool to help you repeat the same job for multiple variables. In the documentation, you can see an example like this:

jobs:
  example_matrix:
    strategy:
      matrix:
        version: [10, 12, 14]
        os: [ubuntu-latest, windows-latest]

As you can see, you could easily run a job for each version and an operating system. But, what if you wanted to run multiple jobs from a list of 1:1 key-value pairs?

Why did we use this?

For my software development team’s project, we needed to map these key-value pairs. That’s because our monorepo contained multiple Function Apps that had a slightly different naming from the actual name in Azure. For example, a function app might be named “Account” in the monorepo, but, in Azure, it was named “Accounts.” Without having to rename any function apps, we needed a 1:1 key-value pair to accommodate for this mismatch of the Azure Function Apps and the directory name when trying to deploy each of them in CI/CD.

So how did we do it?

We created key-value pair where the key to indicate whether the name was in the monorepo or Azure and the value was the Function App name. A matrix suited our situation. That’s because, in continuous deployment, we wanted the directory’s name from the key func-app-name to be used to download the zipped function app and deploy the zipped file to Azure with the name from the key azure-name.

  deploy-to-azure-specially-named-func-apps:
    runs-on: ubuntu-latest
    needs: build-and-test
    strategy:
        matrix:
          target: 
              - func-app-name: 'notifications'
                azure-name: 'notification'
              - func-app-name: 'accounts'
                azure-name: 'account'
    steps:
      - uses: actions/download-artifact@v4
        name: Download zipped Function Apps
        with: 
          name: ${{ matrix.target.func-app-name }}-artifact
      - name: azure login 
        uses: azure/login@v1
        with:
          creds: ${{ secrets.AZURE_SERVICE_PRINCIPLE_SECRET }}
      - name: Publish function apps
        uses: Azure/functions-action@v1
        with:
          app-name: ${{ matrix.target.azure-name }}
          package: ${{ matrix.target.func-app-name }}.zip

Final Thoughts

I’ve only provided a specific situation of when my team used key-value pairs in a matrix with GitHub Actions. However, I’m sure this might be helpful in other scenarios. Perhaps instead of using the matrix to run a specific OS and version, you need to pair several types OS to a version. Whatever situation you come across, I hope this helps.

NOTE: Shout out to @atemate for showing another example of how to do this.