.github/workflows: configure some workflows to run as part of the merge_queue

- Add merge_group for event triggering
- Add a minimal parameter to the e2e-matrix so that we run only one
  set of e2e tests on merge.
- Update DEVELOPMENT.md to explain the mergue queue implementation.

Signed-off-by: Vincent Demeester <vdemeest@redhat.com>

Author: vdemeester

.github/workflows/ci.yaml

@@ -1,6 +1,8 @@
 name: ci
 
-on: [pull_request]
+on:
+  pull_request:
+  merge_group:
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull-request.number || github.ref }}
@@ -147,3 +149,5 @@ jobs:
   e2e-tests:
     needs: [build]
     uses: ./.github/workflows/e2e-matrix.yml
+    with:
+      minimal: ${{ github.event_name == 'merge_group' }}

.github/workflows/dependency-review.yml

@@ -7,7 +7,9 @@
 #
 # Source repository: https://github.com/actions/dependency-review-action
 name: 'Dependency Review'
-on: [pull_request]
+on:
+  pull_request:
+  merge_group:
 
 permissions:
   contents: read

.github/workflows/e2e-matrix.yml

@@ -1,7 +1,14 @@
 name: Tekton Integration
 # Adapted from https://github.com/mattmoor/mink/blob/master/.github/workflows/minkind.yaml
 
-on: [workflow_call]
+on:
+  workflow_call:
+    inputs:
+      minimal:
+        description: 'Run minimal matrix (aka only one job)'
+        required: false
+        type: boolean
+        default: false
 
 defaults:
   run:
@@ -36,7 +43,7 @@ jobs:
         - k8s-name: k8s-latest
           k8s-version: v1.34.x
 
-        # Limit arm64: only run k8s-latest on arm64 (alpha and beta), skip oldest on arm64
+        # Limit arm64: only run k8s-latest on arm64 (stable), skip oldest on arm64
         exclude:
         - k8s-name: k8s-oldest
           os: ubuntu-24.04-arm
@@ -53,7 +60,9 @@ jobs:
 
     steps:
     - name: Free disk space
-      if: ${{ matrix.os != 'ubuntu-24.04-arm' }}
+      if: |
+        matrix.os != 'ubuntu-24.04-arm' &&
+        (!inputs.minimal || (matrix.os == 'ubuntu-latest' && matrix.k8s-name == 'k8s-latest' && matrix.feature-flags == 'stable'))
       run: |
         echo "--- Disk space before cleanup ---"
         df -h
@@ -65,12 +74,16 @@ jobs:
         echo "--- Disk space after cleanup ---"
         df -h
     - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8  # v5.0.0
+      if: ${{ !inputs.minimal || (matrix.os == 'ubuntu-latest' && matrix.k8s-name == 'k8s-latest' && matrix.feature-flags == 'stable') }}
     - uses: actions/setup-go@44694675825211faa026b3c33043df3e48a5fa00  # v6.0.0
+      if: ${{ !inputs.minimal || (matrix.os == 'ubuntu-latest' && matrix.k8s-name == 'k8s-latest' && matrix.feature-flags == 'stable') }}
       with:
         go-version-file: "go.mod"
     - uses: ko-build/setup-ko@d006021bd0c28d1ce33a07e7943d48b079944c8d # v0.9
+      if: ${{ !inputs.minimal || (matrix.os == 'ubuntu-latest' && matrix.k8s-name == 'k8s-latest' && matrix.feature-flags == 'stable') }}
 
     - name: Install Dependencies
+      if: ${{ !inputs.minimal || (matrix.os == 'ubuntu-latest' && matrix.k8s-name == 'k8s-latest' && matrix.feature-flags == 'stable') }}
       working-directory: ./
       run: |
         echo '::group:: install go-junit-report'
@@ -84,6 +97,7 @@ jobs:
         echo "${GOPATH}/bin" >> "$GITHUB_PATH"
 
     - name: Run tests
+      if: ${{ !inputs.minimal || (matrix.os == 'ubuntu-latest' && matrix.k8s-name == 'k8s-latest' && matrix.feature-flags == 'stable') }}
       run: |
         # This is a hack to make sure binary in /bin from the base image are not picked by default
         # On ubuntu-arm, there is a /bin/go that shadows the one setup-go installs
@@ -98,6 +112,7 @@ jobs:
           --e2e-env ./test/e2e-tests-kind-${{ matrix.feature-flags }}.env
 
     - name: Upload test results
+      if: ${{ !inputs.minimal || (matrix.os == 'ubuntu-latest' && matrix.k8s-name == 'k8s-latest' && matrix.feature-flags == 'stable') }}
       uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
       with:
         name: ${{ matrix.k8s-version }}-${{ matrix.feature-flags }}-${{ matrix.os }}

.github/workflows/go-coverage.yml

@@ -6,6 +6,7 @@ permissions:
 on:
   pull_request:
     branches: ["main"]
+  merge_group:
   push:
     branches: ["main"]
   # run at least once every 2 months to prevent the coverage artifact from expiring

DEVELOPMENT.md

@@ -291,6 +291,60 @@ as follows.
 
 ---
 
+## Pull Request Merge Queue
+
+This repository uses GitHub's merge queue to ensure the `main` branch remains stable and free from integration conflicts. The merge queue automatically validates that approved pull requests can be merged cleanly with the latest version of `main` before allowing them to land.
+
+### How It Works
+
+When your pull request is approved and all required checks pass:
+
+1. **Add to Queue**: An approver adds your PR to the merge queue (either manually or automatically based on labels/approvals)
+2. **Temporary Merge**: GitHub creates a temporary branch (`gh-readonly-queue/main/pr-{number}-{sha}`) that merges your PR with the latest `main`
+3. **Validation**: Required CI checks run on this merged state to verify compatibility
+4. **Automatic Merge**: If all checks pass, your PR is automatically merged to `main`
+5. **Failure Handling**: If checks fail on the merged state, your PR is removed from the queue and you'll need to rebase/fix conflicts
+
+### CI Behavior in Merge Queue
+
+To keep the merge queue fast and efficient, the CI matrix is optimized differently for merge queue builds versus regular PR builds:
+
+**Regular Pull Request Builds:**
+- Full e2e test matrix: 18 configurations
+  - 2 architectures (amd64, arm64)
+  - 2 Kubernetes versions (1.28, 1.34)
+  - 3 feature flag sets (stable, beta, alpha)
+- Comprehensive validation before approval
+
+**Merge Queue Builds:**
+- Minimal e2e test matrix: 1 configuration
+  - Single architecture: ubuntu-latest (amd64)
+  - Latest Kubernetes: 1.34
+  - Stable feature flags only
+- Faster validation focused on integration conflicts
+- Full matrix already validated during PR review
+
+This optimization significantly reduces merge queue time while maintaining safety, since your PR has already passed the full 18-configuration test matrix during review.
+
+### What You Need to Know
+
+- **PR reviews unchanged**: Continue developing and testing PRs as usual - all checks must pass before your PR can enter the queue
+- **Automatic process**: Once approved, the merge queue handles merging automatically
+- **Stay up-to-date**: Keep your PR rebased on `main` to minimize queue failures
+- **Queue failures**: If your PR fails in the queue, check for:
+  - Merge conflicts with recent changes to `main`
+  - Integration issues with other recently merged PRs
+  - Flaky tests (less common with minimal matrix)
+
+### Benefits
+
+- **Never break main**: Changes are only merged if they work with the latest code
+- **No merge conflicts**: Incompatible changes are detected before landing
+- **Reduced CI load**: Optimized test matrix for queue builds saves resources
+- **Higher velocity**: Automated merging eliminates manual merge bottlenecks
+
+---
+
 ## Building and deploying
 
 ### Setup a Kubernetes cluster