From df2e979d7e03ba84a503e3d90975a599d484b9e0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9=20A=2E=20Gomes?= <andremegafone@gmail.com>
Date: Mon, 16 Mar 2026 19:37:54 +0200
Subject: [PATCH] fix(ci): Skip build on empty build matrix (#3271)

Closes #3179
---
 .github/workflows/build-user-config.yml | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/build-user-config.yml b/.github/workflows/build-user-config.yml
index 638afb751..4786a1463 100644
--- a/.github/workflows/build-user-config.yml
+++ b/.github/workflows/build-user-config.yml
@@ -30,17 +30,28 @@ jobs:
     name: Fetch Build Keyboards
     outputs:
       build_matrix: ${{ env.build_matrix }}
+      has_valid_build_matrix: ${{ steps.fetch.outputs.has_valid_build_matrix }}
     steps:
       - name: Checkout
         uses: actions/checkout@v4
 
       - name: Fetch Build Matrix
+        id: fetch
         run: |
-          echo "build_matrix=$(yq -oj -I0 '${{ inputs.build_matrix_path }}')" >> $GITHUB_ENV
-          yq -oj "${{ inputs.build_matrix_path }}"
+          matrix_content=$(yq -oj -I0 '${{ inputs.build_matrix_path }}')
+
+          if [ -z "$matrix_content" ] || [ "$matrix_content" = "null" ]; then
+            echo "::notice file=${{inputs.build_matrix_path}},title=Empty build matrix file::To add a keyboard to the build, see https://zmk.dev/docs/user-setup#add-a-keyboard."
+            echo "has_valid_build_matrix=false" >> $GITHUB_OUTPUT
+          else
+            echo "build_matrix=$matrix_content" >> $GITHUB_ENV
+            echo "has_valid_build_matrix=true" >> $GITHUB_OUTPUT
+            echo "$matrix_content"
+          fi
 
   build:
     runs-on: ubuntu-latest
+    if: needs.matrix.outputs.has_valid_build_matrix == 'true'
     container:
       image: zmkfirmware/zmk-build-arm:stable
     needs: matrix
@@ -213,6 +224,7 @@ jobs:
 
   merge:
     runs-on: ubuntu-latest
+    if: needs.matrix.outputs.has_valid_build_matrix == 'true'
     needs: build
     name: Merge Output Artifacts
     steps: