feat(cpp-matrix): sort entries by historical failure rate

Author: alandefreitas

.github/workflows/ci.yml

@@ -58,6 +58,7 @@ jobs:
           extra-values: |
             vcpkg-packages: {{#if (not fetch-content)}}fmt{{/if}}
             address-model: {{#if (eq arch 'x86')}}32{{else}}64{{/if}}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
 
   build:
     needs: cpp-matrix

boost-clone/dist/index.js

@@ -707,6 +707,44 @@ inputs:
     required: false
     default: 'true'
 
+  # -----------------------------------------------------------------
+  # Failure rate sorting
+  # -----------------------------------------------------------------
+  sort-by-failure-rate:
+    description: |
+      Sort matrix entries by historical failure rate.
+
+      The action fetches recent workflow run history and calculates the failure rate
+      for each matrix entry based on job name matching. Entries with higher failure rates are
+      sorted first (stable sort preserving existing order for equal rates).
+
+      This is useful when combined with `max-parallel` or limited runners, as it ensures jobs
+      most likely to fail run first, providing faster feedback.
+
+      When enabled, the summary table includes a "Failure Rate" column.
+
+      Requires `github-token` to be set for API access. If failure rates cannot be calculated
+      (no token, no history, API errors), the action continues gracefully without error.
+    required: false
+    default: 'true'
+
+  failure-rate-runs:
+    description: |
+      Number of recent workflow runs to analyze when calculating failure rates.
+
+      Only used when `sort-by-failure-rate` is enabled.
+    required: false
+    default: '20'
+
+  github-token:
+    description: |
+      GitHub token for API access when fetching workflow run history for failure rate calculation.
+
+      Required when `sort-by-failure-rate` is enabled. Pass `${{ secrets.GITHUB_TOKEN }}` or
+      `${{ github.token }}`. Alternatively, set the `GITHUB_TOKEN` environment variable in your
+      workflow step.
+    required: false
+    default: ''
 
 outputs:
   matrix:

boost-clone/dist/index.js.map

@@ -15,6 +15,7 @@
   "license": "Boost Software License 1.0",
   "dependencies": {
     "@actions/core": "^1.11.1",
+    "@actions/http-client": "^3.0.0",
     "handlebars": "^4.7.8",
     "semver": "^7.7.3",
     "setup-program": "*",

cmake-workflow/dist/index.js

@@ -188,7 +188,10 @@ describe('generateMatrix', () => {
             output_file: undefined,
             log_matrix: false,
             generate_summary: false,
-            trace_commands: false
+            trace_commands: false,
+            sort_by_failure_rate: false,
+            failure_rate_runs: 20,
+            github_token: ''
         };
         const matrix = await generateMatrix(inputs);
         expect(matrix.length === 0).toBe(false);
@@ -225,7 +228,10 @@ describe('generateMatrix', () => {
             output_file: undefined,
             log_matrix: false,
             generate_summary: false,
-            trace_commands: false
+            trace_commands: false,
+            sort_by_failure_rate: false,
+            failure_rate_runs: 20,
+            github_token: ''
         };
         try {
             await generateMatrix(inputs);
@@ -268,7 +274,10 @@ test('msvc x86 entries prefer arch metadata over /m32 flags', async () => {
         output_file: undefined,
         log_matrix: false,
         generate_summary: false,
-        trace_commands: false
+        trace_commands: false,
+        sort_by_failure_rate: false,
+        failure_rate_runs: 20,
+        github_token: ''
     };
     const matrix = await generateMatrix(inputs);
     const msvcX86Entry = matrix.find(entry => entry.compiler === 'msvc' && entry.x86 === true);
@@ -310,7 +319,10 @@ test('non-x86 entries default arch to x64 unless overridden', async () => {
         output_file: undefined,
         log_matrix: false,
         generate_summary: false,
-        trace_commands: false
+        trace_commands: false,
+        sort_by_failure_rate: false,
+        failure_rate_runs: 20,
+        github_token: ''
     };
     const matrix = await generateMatrix(inputs);
     const gccEntry = matrix.find(entry => entry.compiler === 'gcc');
@@ -353,7 +365,10 @@ test('generates entries for compilers with no known versions', async () => {
         output_file: undefined,
         log_matrix: false,
         generate_summary: false,
-        trace_commands: false
+        trace_commands: false,
+        sort_by_failure_rate: false,
+        failure_rate_runs: 20,
+        github_token: ''
     };
     const warnSpy = jest.spyOn(core, 'warning').mockImplementation(() => { });
     try {