ci: Reduce unnecessary builds and compiler-cache pressure

.github/detray-traccc-filters.yml

@@ -0,0 +1,37 @@
+# Merge-group filters: include shared build inputs as well as the package.
+# Keep these conservative when the standalone builds gain new dependencies.
+detray:
+  - 'Detray/**'
+  # Standalone Detray uses ACTS' header compilation and codegen modules.
+  - 'cmake/**'
+  - 'codegen/**'
+  - 'thirdparty/**'
+  - 'CMakeLists.txt'
+  - 'CMakePresets.json'
+  - 'CI/**'
+  - '.github/actions/**'
+  - '.github/workflows/detray.yml'
+  - '.github/detray-traccc-filters.yml'
+
+traccc:
+  - 'Traccc/**'
+  - 'Detray/**'
+  # Traccc/extern/acts builds the colocated ACTS tree, including Core and
+  # plugins. Keep the source roots conservative as its presets evolve.
+  - 'Core/**'
+  - 'Plugins/**'
+  - 'Fatras/**'
+  - 'Alignment/**'
+  - 'Examples/**'
+  - 'Tests/**'
+  - 'Python/**'
+  - 'cmake/**'
+  - 'codegen/**'
+  - 'thirdparty/**'
+  - 'CMakeLists.txt'
+  - 'CMakePresets.json'
+  - 'version_number'
+  - 'CI/**'
+  - '.github/actions/**'
+  - '.github/workflows/traccc.yml'
+  - '.github/detray-traccc-filters.yml'

.github/workflows/builds.yml

@@ -50,6 +50,9 @@ jobs:
       packages: read
     container: registry.cern.ch/ghcr.io/acts-project/ubuntu2604:90
     env:
+      # The FPE build evicted objects during compilation at 500 MB. Cache
+      # retention removes superseded main archives to make room for this.
+      CCACHE_MAXSIZE: 1G
       INSTALL_DIR: ${{ github.workspace }}/install
       ACTS_LOG_FAILURE_THRESHOLD: WARNING
 

.github/workflows/ccache-retention.yml

@@ -0,0 +1,48 @@
+name: Compiler cache retention
+
+on:
+  # Only trusted main runs can trigger deletion; no PR artifacts or source
+  # are consumed. Checkout below always uses main, not the triggering SHA.
+  workflow_run: # zizmor: ignore[dangerous-triggers]
+    workflows: [Builds, Analysis, Detray, PyPI]
+    branches: [main]
+    types: [completed]
+  workflow_dispatch:
+    inputs:
+      apply:
+        description: Delete superseded main compiler-cache archives
+        type: boolean
+        default: false
+
+permissions: {}
+
+concurrency:
+  group: ccache-retention
+  cancel-in-progress: false
+
+jobs:
+  prune:
+    if: >-
+      github.repository == 'acts-project/acts' &&
+      ((github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/main') ||
+      (github.event.workflow_run.head_repository.full_name == github.repository &&
+      (github.event.workflow_run.event == 'push' || github.event.workflow_run.event == 'schedule')))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      actions: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: main
+          persist-credentials: false
+      - name: Retain newest compiler caches
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          APPLY: ${{ github.event_name == 'workflow_run' || inputs.apply }}
+        run: |
+          args=()
+          if [[ "$APPLY" == "true" ]]; then
+            args+=(--apply)
+          fi
+          python3 CI/prune_ccache.py "${args[@]}"

.github/workflows/checks.yml

@@ -114,8 +114,9 @@ jobs:
 
   # The CI tooling's own self-tests, which otherwise have no feedback loop:
   # broken tooling fails in some other job that already paid for a container
-  # pull. Grouped because they are pure python and run in seconds; separate
-  # steps so a failure names the suite. test_public_api_surface.py stays in
+  # pull. Grouped because they are pure Python and run in seconds.
+  # Use explicit test paths to avoid collecting other CI tools.
+  # test_public_api_surface.py stays in
   # `api_surface` -- it skips its drift check without doxygen on PATH.
   self_tests:
     runs-on: ubuntu-slim
@@ -126,12 +127,18 @@ jobs:
       - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: '3.14'
-      - name: Dependency lockfile selection
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          enable-cache: false
+      - name: CI tooling self-tests
         run: >
+          uv run --no-project --no-build
+          --with-requirements CI/self_tests/requirements.txt
+          python -m pytest -q
           CI/dependencies/test_select_lockfile.py
-      - name: Deprecated-docs checker
-        run: >
           CI/public_api/test_check_deprecated_docs.py
+          CI/test_check_unused_files.py
+          CI/test_prune_ccache.py
 
   codegen_prebuilt:
     # Pre-generates the code the build would otherwise generate, then checks

.github/workflows/detray.yml

@@ -13,16 +13,16 @@ on:
     paths:
       - "Detray/**"
       - ".github/workflows/detray.yml"
+      - ".github/detray-traccc-filters.yml"
   pull_request:
     branches:
       - main
     paths:
       - "Detray/**"
       - ".github/workflows/detray.yml"
-  # merge_group does not support path filters, so this runs on every queue
-  # entry targeting main, not just ones touching Detray/. Only required via
-  # merge-sentinel's "Detray / *" pattern, which is itself path-gated, so a
-  # non-Detray entry running this wastes compute but doesn't block merging.
+      - ".github/detray-traccc-filters.yml"
+  # The changes job applies path filtering to merge groups, which do not
+  # support the workflow-level path filters above.
   merge_group:
     types: [checks_requested]
 
@@ -45,9 +45,34 @@ env:
 
 # All the different build/test jobs.
 jobs:
+  # Like Builds/changes, gate jobs rather than suppressing check reporting.
+  # PR/push triggers already filter paths; only merge groups need a checkout
+  # and a comparison against the base SHA carried by the event.
+  changes:
+    if: github.event_name == 'merge_group'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    outputs:
+      relevant: ${{ steps.filter.outputs.detray }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: dorny/paths-filter@ceb8a2b8f2d89434be7ff52d3de7ec3738c5cc9d # v4.0.3
+        id: filter
+        with:
+          base: ${{ github.event.merge_group.base_sha }}
+          ref: ${{ github.event.merge_group.head_sha }}
+          filters: .github/detray-traccc-filters.yml
 
   # Native build jobs.
   native:
+    needs: changes
+    # !cancelled() allows PR/push jobs through when changes is skipped.
+    if: >-
+      !cancelled() && (github.event_name != 'merge_group' ||
+      (needs.changes.result == 'success' && needs.changes.outputs.relevant == 'true'))
 
     # The different build modes to test.
     strategy:
@@ -93,6 +118,11 @@ jobs:
 
   # Containerised build jobs.
   host-container:
+    needs: changes
+    # !cancelled() allows PR/push jobs through when changes is skipped.
+    if: >-
+      !cancelled() && (github.event_name != 'merge_group' ||
+      (needs.changes.result == 'success' && needs.changes.outputs.relevant == 'true'))
 
     # The different build modes to test.
     strategy:
@@ -192,6 +222,11 @@ jobs:
   # Containerised build jobs. Debug compile checks only -- nothing here is
   # executed. CUDA has its own build/test pair below.
   device-container:
+    needs: changes
+    # !cancelled() allows PR/push jobs through when changes is skipped.
+    if: >-
+      !cancelled() && (github.event_name != 'merge_group' ||
+      (needs.changes.result == 'success' && needs.changes.outputs.relevant == 'true'))
 
     # The different build modes to test.
     strategy:
@@ -291,6 +326,11 @@ jobs:
   # build down to what the GPU job actually runs.
   # ─────────────────────────────────────────────────────────────────────
   cuda:
+    needs: changes
+    # !cancelled() allows PR/push jobs through when changes is skipped.
+    if: >-
+      !cancelled() && (github.event_name != 'merge_group' ||
+      (needs.changes.result == 'success' && needs.changes.outputs.relevant == 'true'))
     name: "cuda (${{ matrix.SCALAR_TYPE }})"
     runs-on: [self-hosted, linux, x64, husk-size-standard]
     permissions:
@@ -405,6 +445,7 @@ jobs:
   # ─────────────────────────────────────────────────────────────────────
   cuda-test:
     needs: [cuda]
+    if: ${{ !cancelled() && needs.cuda.result == 'success' }}
     runs-on: [self-hosted, linux, x64, gpu-nvidia]
     permissions:
       contents: read

.github/workflows/traccc.yml

@@ -20,18 +20,17 @@ on:
       - "Traccc/**"
       - "Detray/**"
       - ".github/workflows/traccc.yml"
+      - ".github/detray-traccc-filters.yml"
   pull_request:
     branches:
       - main
     paths:
       - "Traccc/**"
       - "Detray/**"
       - ".github/workflows/traccc.yml"
-  # merge_group does not support path filters, so this runs on every queue
-  # entry targeting main, not just ones touching Traccc/ or Detray/. Only
-  # required via merge-sentinel's "Traccc / *" pattern, which is itself
-  # path-gated, so a non-Traccc entry running this wastes compute but doesn't
-  # block merging.
+      - ".github/detray-traccc-filters.yml"
+  # The changes job applies path filtering to merge groups, which do not
+  # support the workflow-level path filters above.
   merge_group:
     types: [checks_requested]
 
@@ -42,7 +41,33 @@ concurrency:
   cancel-in-progress: ${{ github.event_name != 'merge_group' }}
 
 jobs:
+  # Like Builds/changes, gate jobs rather than suppressing check reporting.
+  # PR/push triggers already filter paths; only merge groups need a checkout
+  # and a comparison against the base SHA carried by the event.
+  changes:
+    if: github.event_name == 'merge_group'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    outputs:
+      relevant: ${{ steps.filter.outputs.traccc }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: dorny/paths-filter@ceb8a2b8f2d89434be7ff52d3de7ec3738c5cc9d # v4.0.3
+        id: filter
+        with:
+          base: ${{ github.event.merge_group.base_sha }}
+          ref: ${{ github.event.merge_group.head_sha }}
+          filters: .github/detray-traccc-filters.yml
+
   containers:
+    needs: changes
+    # !cancelled() allows PR/push jobs through when changes is skipped.
+    if: >-
+      !cancelled() && (github.event_name != 'merge_group' ||
+      (needs.changes.result == 'success' && needs.changes.outputs.relevant == 'true'))
     name: ${{ matrix.platform.name }}-${{ matrix.build }}
     runs-on: ubuntu-latest
     container: ${{ matrix.platform.container }}
@@ -245,6 +270,7 @@ jobs:
   # ─────────────────────────────────────────────────────────────────────
   cuda-test:
     needs: [containers]
+    if: ${{ !cancelled() && needs.containers.result == 'success' }}
     runs-on: [self-hosted, linux, x64, gpu-nvidia]
     permissions:
       contents: read

.merge-sentinel.yml

@@ -42,6 +42,7 @@ rules:
      - "Detray/*"
      - "Detray/**/*"
      - ".github/workflows/detray.yml"
+     - ".github/detray-traccc-filters.yml"
     required_pattern:
      - "Detray / *"
 
@@ -57,5 +58,6 @@ rules:
      - "Traccc/*"
      - "Traccc/**/*"
      - ".github/workflows/traccc.yml"
+     - ".github/detray-traccc-filters.yml"
     required_pattern:
      - "Traccc / *"

CI/check_unused_files.py

@@ -155,11 +155,12 @@ def keep(name):
 
 
 def file_can_be_removed(searchstring, scope):
-    cmd = "grep -IR '" + searchstring + "' " + " ".join(scope)
-
-    p = subprocess.Popen(cmd, shell=True, stdout=subprocess.PIPE)
-    output, _ = p.communicate()
-    return output == b""
+    # Only existence matters: stop at the first match instead of scanning the
+    # entire tree and collecting every matching line for each candidate.
+    result = subprocess.run(["grep", "-IRq", "--", searchstring, *scope])
+    if result.returncode not in (0, 1):
+        result.check_returncode()
+    return result.returncode == 1
 
 
 def count_files(path="."):

CI/cibuildwheel.sh

@@ -22,7 +22,9 @@ export CIBW_SKIP="*-musllinux* *-manylinux_i686"
 SETUP_CMD="bash {package}/CI/dependencies/setup.sh -t v23.3.1 -d deps -e env.sh"
 export CIBW_BEFORE_ALL_LINUX="dnf install -y bc ccache && ${SETUP_CMD}"
 export CIBW_BEFORE_ALL_MACOS="brew install ninja ccache && ${SETUP_CMD}"
-export CIBW_ENVIRONMENT_PASS="CI GITHUB_TOKEN"
+# Linux wheels build in a container: the job's ccache ceiling must be passed
+# explicitly or the container uses ccache's default (5 GB).
+export CIBW_ENVIRONMENT_PASS="CI GITHUB_TOKEN CCACHE_MAXSIZE"
 export CIBW_BEFORE_BUILD="ccache -z"
 export CIBW_ENVIRONMENT_LINUX="CMAKE_PREFIX_PATH=\$PWD/deps/venv:\$PWD/deps/view CCACHE_DIR=/host${CCACHE_DIR} LD_LIBRARY_PATH=\$PWD/deps/view/lib64:\$PWD/deps/view/lib:\$PWD/deps/venv/lib64:\$PWD/deps/venv/lib"
 export CIBW_ENVIRONMENT_MACOS="CMAKE_PREFIX_PATH=\$PWD/deps/venv:\$PWD/deps/view CCACHE_DIR=${CCACHE_DIR} MACOSX_DEPLOYMENT_TARGET=26.0"