ci: add gate job to CodeQL workflow for text-only PRs (#6346)

* ci: add gate job to CodeQL workflow for text-only PRs

Remove paths-ignore from the workflow trigger and add a check-changes
job with dorny/paths-filter to detect code changes at the job level.
This ensures the workflow always triggers so the codeql-complete gate
job can report a passing status when analyze is skipped, preventing
text-only PRs from being blocked by required status checks.

* ci: check both check-changes and analyze results in gate job

Add check-changes to the needs array of codeql-complete so that a
failure in the change-detection job is not silently treated as a
skipped analysis.

.github/workflows/codeql.yml

@@ -3,12 +3,8 @@ name: "CodeQL"
 on:
   push:
     branches: [ "develop" ]
-    paths-ignore:
-      - '**.md'
   pull_request:
     branches: [ "develop" ]
-    paths-ignore:
-      - '**.md'
   schedule:
     - cron: "16 7 * * 0"
   workflow_dispatch:  # Allow manual triggering
@@ -17,8 +13,34 @@ permissions:
   contents: read
 
 jobs:
+  check-changes:
+    name: Check for code changes
+    runs-on: ubuntu-latest
+    outputs:
+      has_code_changes: ${{ steps.filter.outputs.code }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - name: Check for code changes
+        uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
+        id: filter
+        with:
+          filters: |
+            code:
+              - '**/*.c'
+              - '**/*.h'
+              - '**/*.cpp'
+              - '**/*.hpp'
+              - '**/CMakeLists.txt'
+              - '**/*.cmake'
+
   analyze:
     name: Analyze
+    needs: check-changes
+    if: >-
+      needs.check-changes.outputs.has_code_changes == 'true' ||
+      github.event_name == 'schedule' ||
+      github.event_name == 'workflow_dispatch'
     runs-on: ubuntu-latest
     permissions:
       actions: read
@@ -183,3 +205,29 @@ jobs:
         uses: github/codeql-action/upload-sarif@e34fc2711fb7964ca6850c8a8382121f34745f3b # v4.32.4
         with:
           sarif_file: sarif-results/cpp.sarif
+
+  # Gate job: always runs even when 'analyze' is skipped (e.g., text-only PRs).
+  # Use "CodeQL / codeql-complete" as the required status check instead of "CodeQL / Analyze".
+  codeql-complete:
+    name: codeql-complete
+    if: always()
+    needs: [check-changes, analyze]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check analyze result
+        run: |
+          check_result="${{ needs.check-changes.result }}"
+          analyze_result="${{ needs.analyze.result }}"
+
+          if [ "$check_result" != "success" ]; then
+            echo "check-changes job failed with result: $check_result"
+            exit 1
+          fi
+
+          if [ "$analyze_result" = "success" ] || [ "$analyze_result" = "skipped" ]; then
+            echo "CodeQL analysis passed or was skipped (text-only change)."
+            exit 0
+          else
+            echo "CodeQL analysis failed with result: $analyze_result"
+            exit 1
+          fi