ci: skip builds for documentation-only changes

Author: PastaPastaPasta

.github/workflows/build.yml

@@ -8,6 +8,7 @@ permissions:
   actions: read
   contents: read
   packages: write
+  pull-requests: read
 
 concurrency:
   group: |
@@ -25,6 +26,7 @@ jobs:
     runs-on: ${{ vars.RUNNER_CHECK_SKIP || 'ubuntu-24.04-arm' }}
     outputs:
       skip: ${{ steps.skip-check.outputs.skip }}
+      run-build-tests: ${{ steps.classify-changes.outputs.run-build-tests }}
       runner-amd64: ${{ steps.select-runner.outputs.runner_amd64 }}
       runner-arm64: ${{ steps.select-runner.outputs.runner_arm64 }}
       use-blacksmith: ${{ steps.select-runner.outputs.use_blacksmith }}
@@ -39,18 +41,102 @@ jobs:
         run: |
           if [[ "${{ github.event_name }}" == "push" && "${{ vars.SKIP_ON_PUSH }}" != "" ]]; then
             echo "Skipping build on push due to SKIP_ON_PUSH environment variable"
-            echo "skip=true" >> $GITHUB_OUTPUT
+            echo "skip=true" >> "$GITHUB_OUTPUT"
           elif [[ "${{ github.event_name }}" == "pull_request_target" && "${{ vars.SKIP_ON_PR }}" != "" ]]; then
             echo "Skipping build on pull request due to SKIP_ON_PR environment variable"
-            echo "skip=true" >> $GITHUB_OUTPUT
+            echo "skip=true" >> "$GITHUB_OUTPUT"
           else
-            echo "skip=false" >> $GITHUB_OUTPUT
+            echo "skip=false" >> "$GITHUB_OUTPUT"
           fi
 
       - name: Checkout code
         if: ${{ steps.skip-check.outputs.skip == 'false' }}
         uses: actions/checkout@v6
 
+      - name: Collect changed paths
+        id: changed-paths
+        if: ${{ steps.skip-check.outputs.skip == 'false' }}
+        uses: actions/github-script@v8
+        env:
+          CHANGED_PATHS_FILE: ${{ runner.temp }}/changed-paths.json
+        with:
+          script: |
+            const fs = require('fs');
+            let complete = true;
+            let files = [];
+
+            try {
+              if (context.eventName === 'pull_request_target') {
+                files = await github.paginate(github.rest.pulls.listFiles, {
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  pull_number: context.payload.pull_request.number,
+                  per_page: 100,
+                });
+                if (files.length >= 3000) {
+                  complete = false;
+                  core.warning('Pull request file list reached the GitHub API limit');
+                }
+              } else if (context.eventName === 'push') {
+                const after = context.payload.after;
+                if (context.ref.startsWith('refs/tags/')) {
+                  complete = false;
+                } else {
+                  // Comparing with the last successful run preserves coverage when a
+                  // later push cancels an in-flight run before its build matrix finishes.
+                  const previousRuns = await github.rest.actions.listWorkflowRuns({
+                    owner: context.repo.owner,
+                    repo: context.repo.repo,
+                    workflow_id: 'build.yml',
+                    branch: context.ref.replace('refs/heads/', ''),
+                    event: 'push',
+                    status: 'success',
+                    per_page: 1,
+                  });
+                  const previousSha = previousRuns.data.workflow_runs[0]?.head_sha;
+                  if (!previousSha) {
+                    complete = false;
+                  } else {
+                    const comparison = await github.rest.repos.compareCommitsWithBasehead({
+                      owner: context.repo.owner,
+                      repo: context.repo.repo,
+                      basehead: `${previousSha}...${after}`,
+                    });
+                    files = comparison.data.files || [];
+                    if (files.length >= 300) {
+                      complete = false;
+                      core.warning('Push file list reached the GitHub API limit');
+                    }
+                  }
+                }
+              } else {
+                complete = false;
+              }
+            } catch (error) {
+              complete = false;
+              core.warning(`Unable to collect a complete changed path list: ${error.message}`);
+            }
+
+            const paths = [...new Set(files.flatMap(file =>
+              [file.filename, file.previous_filename].filter(Boolean)
+            ))].sort();
+            fs.writeFileSync(process.env.CHANGED_PATHS_FILE, JSON.stringify(paths));
+            core.setOutput('complete', complete.toString());
+
+      - name: Classify changed paths
+        id: classify-changes
+        if: ${{ steps.skip-check.outputs.skip == 'false' }}
+        env:
+          CHANGED_PATHS_COMPLETE: ${{ steps.changed-paths.outputs.complete }}
+          CHANGED_PATHS_FILE: ${{ runner.temp }}/changed-paths.json
+        run: |
+          if ! python3 .github/workflows/classify_ci_changes.py \
+            --complete "$CHANGED_PATHS_COMPLETE" "$CHANGED_PATHS_FILE"; then
+            echo "Path classification failed; running the full build and test matrix"
+            echo "run-build-tests=true" >> "$GITHUB_OUTPUT"
+            echo "decision-reason=path classification failed" >> "$GITHUB_OUTPUT"
+          fi
+
       - name: Select runners
         id: select-runner
         if: ${{ steps.skip-check.outputs.skip == 'false' }}
@@ -65,7 +151,9 @@ jobs:
 
       - name: Get base image digest
         id: base-image
-        if: ${{ steps.skip-check.outputs.skip == 'false' }}
+        if: |
+          steps.skip-check.outputs.skip == 'false' &&
+          steps.classify-changes.outputs.run-build-tests == 'true'
         run: |
           # Fetch the canonical manifest digest for ubuntu:noble so the
           # depends cache key changes when Canonical pushes base image
@@ -86,15 +174,19 @@ jobs:
   cache-sources:
     name: Cache depends sources
     needs: [check-skip]
-    if: ${{ needs.check-skip.outputs.skip == 'false' }}
+    if: |
+      needs.check-skip.outputs.skip == 'false' &&
+      needs.check-skip.outputs.run-build-tests == 'true'
     uses: ./.github/workflows/cache-depends-sources.yml
     with:
       runs-on: ${{ needs.check-skip.outputs['runner-arm64'] }}
 
   container:
     name: Build container
     needs: [check-skip]
-    if: ${{ needs.check-skip.outputs.skip == 'false' }}
+    if: |
+      needs.check-skip.outputs.skip == 'false' &&
+      needs.check-skip.outputs.run-build-tests == 'true'
     uses: ./.github/workflows/build-container.yml
     with:
       context: ./contrib/containers/ci

.github/workflows/classify_ci_changes.py

@@ -0,0 +1,143 @@
+# Copyright (c) 2026 The Dash Core developers
+# Distributed under the MIT software license, see the accompanying
+# file COPYING or http://www.opensource.org/licenses/mit-license.php.
+
+import argparse
+import json
+import os
+from pathlib import PurePosixPath
+from typing import Dict, List, Optional, Sequence
+
+
+EXCLUDED_EXACT_PATHS = {
+    "doc/.gitignore",
+}
+EXCLUDED_PREFIXES = (
+    ".github/ISSUE_TEMPLATE/",
+    ".github/PULL_REQUEST_TEMPLATE/",
+)
+EXCLUDED_DOC_SUFFIXES = {".1", ".5", ".8", ".png", ".svg", ".txt"}
+BUILD_RELEVANT_PATHS = {"COPYING", "doc/README_windows.txt"}
+
+
+def is_excluded_path(path: str) -> bool:
+    if not path or path in BUILD_RELEVANT_PATHS:
+        return False
+    if path in EXCLUDED_EXACT_PATHS or path.startswith(EXCLUDED_PREFIXES):
+        return True
+
+    suffix = PurePosixPath(path).suffix
+    if suffix == ".md":
+        return True
+    return path.startswith("doc/") and suffix in EXCLUDED_DOC_SUFFIXES
+
+
+def classify_changes(paths: Sequence[str], complete: bool) -> Dict[str, object]:
+    unique_paths = sorted(set(paths))
+    if not complete:
+        return {
+            "run_build_tests": True,
+            "reason": "changed path list is incomplete",
+            "paths": unique_paths,
+            "triggering_paths": [],
+        }
+    if not unique_paths:
+        return {
+            "run_build_tests": True,
+            "reason": "no changed paths were reported",
+            "paths": unique_paths,
+            "triggering_paths": [],
+        }
+
+    triggering_paths = [path for path in unique_paths if not is_excluded_path(path)]
+    if triggering_paths:
+        reason = "build-relevant or unclassified paths changed"
+    else:
+        reason = "all changed paths are in CI exclusion zones"
+    return {
+        "run_build_tests": bool(triggering_paths),
+        "reason": reason,
+        "paths": unique_paths,
+        "triggering_paths": triggering_paths,
+    }
+
+
+def load_paths(path: str) -> List[str]:
+    with open(path, "r", encoding="utf-8") as file:
+        paths = json.load(file)
+    if not isinstance(paths, list) or not all(isinstance(item, str) for item in paths):
+        raise ValueError("changed paths must be a JSON array of strings")
+    return paths
+
+
+def write_github_output(path: Optional[str], result: Dict[str, object]) -> None:
+    if not path:
+        return
+    with open(path, "a", encoding="utf-8") as file:
+        file.write(
+            "run-build-tests={}\n".format(
+                "true" if result["run_build_tests"] else "false"
+            )
+        )
+        file.write("decision-reason={}\n".format(result["reason"]))
+
+
+def write_step_summary(
+    path: Optional[str], result: Dict[str, object], complete: bool
+) -> None:
+    if not path:
+        return
+
+    triggering_paths = result["triggering_paths"]
+    with open(path, "a", encoding="utf-8") as file:
+        file.write("### Build and test path classification\n")
+        file.write(
+            "- Changed path list complete: {}\n".format(
+                "yes" if complete else "no"
+            )
+        )
+        file.write("- Changed paths examined: {}\n".format(len(result["paths"])))
+        file.write(
+            "- Full build and test matrix: {}\n".format(
+                "required" if result["run_build_tests"] else "skipped"
+            )
+        )
+        file.write("- Decision: `{}`\n".format(result["reason"]))
+        if triggering_paths:
+            file.write("- Triggering paths (up to 20):\n")
+            for changed_path in triggering_paths[:20]:
+                file.write(
+                    "  - `{}`\n".format(json.dumps(changed_path, ensure_ascii=True))
+                )
+
+
+def parse_args(argv: Sequence[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Classify changed paths for Dash CI.")
+    parser.add_argument("paths_json", help="JSON file containing changed paths")
+    parser.add_argument(
+        "--complete",
+        choices=("true", "false"),
+        required=True,
+        help="Whether the changed path list is known to be complete",
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: Sequence[str]) -> int:
+    args = parse_args(argv)
+    complete = args.complete == "true"
+    result = classify_changes(load_paths(args.paths_json), complete)
+    write_github_output(os.environ.get("GITHUB_OUTPUT"), result)
+    write_step_summary(os.environ.get("GITHUB_STEP_SUMMARY"), result, complete)
+    print(
+        "run-build-tests={} ({})".format(
+            "true" if result["run_build_tests"] else "false", result["reason"]
+        )
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    import sys
+
+    sys.exit(main(sys.argv[1:]))