From ad2988c9daf4cf5895b7d2a631951fb1a52aaf21 Mon Sep 17 00:00:00 2001
From: Artur Do Lago <adolago@users.noreply.github.com>
Date: Mon, 23 Feb 2026 10:17:39 +0100
Subject: [PATCH] ci: gate major optional feature bundles in test matrix

---
 .github/workflows/ci.yml         | 77 +++++++++++++++++++++++++++++++-
 docs/development/CONTRIBUTING.md | 18 ++++++++
 2 files changed, 93 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 45a5ee53..7c02a0d6 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -123,6 +123,77 @@ jobs:
       - name: Run doc tests
         run: cargo test --doc --features ${{ matrix.features }}
 
+  # Gate major optional feature bundles to avoid regressions in less-used modules
+  feature_matrix:
+    name: Feature Bundle Gate (${{ matrix.bundle.name }})
+    needs: check
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        bundle:
+          - name: aws
+            features: aws
+            mode: test
+          - name: docker
+            features: docker
+            mode: test
+          - name: api
+            features: api
+            mode: test
+          - name: database
+            features: database
+            mode: test
+          - name: provisioning
+            features: provisioning
+            mode: test
+          - name: aggregate
+            features: full-provisioning,api,database
+            mode: compile
+
+    steps:
+      - name: Free disk space
+        run: |
+          # Remove unnecessary large directories to free up disk space (~15GB)
+          sudo rm -rf /usr/share/dotnet
+          sudo rm -rf /opt/ghc
+          sudo rm -rf /usr/local/share/boost
+          sudo rm -rf "$AGENT_TOOLSDIRECTORY"
+          # Additional cleanup for more space (~10GB more)
+          sudo rm -rf /usr/local/lib/android
+          sudo rm -rf /opt/hostedtoolcache/CodeQL
+          sudo rm -rf /usr/local/share/powershell
+          sudo rm -rf /usr/share/swift
+          df -h
+
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache cargo registry
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-bundle-${{ matrix.bundle.name }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-bundle-${{ matrix.bundle.name }}-cargo-
+            ${{ runner.os }}-bundle-cargo-
+            ${{ runner.os }}-cargo-
+
+      - name: Compile bundle
+        run: cargo check --all-targets --features "${{ matrix.bundle.features }}" --verbose
+
+      - name: Run bundle tests
+        if: matrix.bundle.mode == 'test'
+        run: cargo test --lib --features "${{ matrix.bundle.features }}" --verbose -- --test-threads=1
+        env:
+          RUST_LOG: debug
+
   # Security audit using cargo-audit
   security:
     name: Security Audit
@@ -215,7 +286,7 @@ jobs:
   # Build release artifacts for all platforms
   build:
     name: Build (${{ matrix.target }})
-    needs: [test, security]
+    needs: [test, feature_matrix, security]
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
@@ -305,7 +376,7 @@ jobs:
   # Summary job that requires all other jobs to pass
   ci-success:
     name: CI Success
-    needs: [check, test, security, coverage, build]
+    needs: [check, test, feature_matrix, security, coverage, build]
     runs-on: ubuntu-latest
     if: always()
     steps:
@@ -313,7 +384,9 @@ jobs:
         run: |
           if [[ "${{ needs.check.result }}" != "success" ]] || \
              [[ "${{ needs.test.result }}" != "success" ]] || \
+             [[ "${{ needs.feature_matrix.result }}" != "success" ]] || \
              [[ "${{ needs.security.result }}" != "success" ]] || \
+             [[ "${{ needs.coverage.result }}" != "success" ]] || \
              [[ "${{ needs.build.result }}" != "success" ]]; then
             echo "One or more jobs failed"
             exit 1
diff --git a/docs/development/CONTRIBUTING.md b/docs/development/CONTRIBUTING.md
index d5878160..b0797abb 100644
--- a/docs/development/CONTRIBUTING.md
+++ b/docs/development/CONTRIBUTING.md
@@ -99,6 +99,24 @@ cargo test --test '*'
 cargo test --features "russh,local"
 ```
 
+### CI Feature Bundle Gate
+
+GitHub Actions enforces a dedicated optional-feature matrix on Linux stable to
+catch regressions outside the default profile:
+
+- Tested bundles: `aws`, `docker`, `api`, `database`, `provisioning`
+- Broad aggregate compile gate: `full-provisioning,api,database`
+
+Use these commands locally when working on optional feature paths:
+
+```bash
+# Compile all targets for a bundle
+cargo check --all-targets --features "<bundle>"
+
+# Run a fast bundle test path (library tests)
+cargo test --lib --features "<bundle>" -- --test-threads=1
+```
+
 ### Running Benchmarks
 
 ```bash