ci(e2e): gate non-GPU E2E behind copy-pr-bot

pimlock · pimlock · commit 24f694f5630c · 2026-04-22T12:58:49.000-07:00
Move `Branch E2E Checks` to the same `pull-request/&lt;N&gt;` + `get-pr-info`
pattern used by GPU tests so self-hosted runners only execute code that
has been explicitly mirrored by copy-pr-bot (automatically for trusted
PRs, via `/ok to test &lt;SHA&gt;` for untrusted ones). A `test:e2e` label on
the PR is still required.

Also:

- Extract the shared gate logic into `.github/actions/pr-gate` so
  `branch-e2e.yml` and `test-gpu.yml` no longer duplicate the SHA/label
  check. The required label is passed as an input.
- Scope permissions per-job in both workflows. Workflow-level defaults
  to `permissions: {}`; builds grant `packages: write`, E2E gets
  `packages: read`, `pr_metadata` gets `contents: read` +
  `pull-requests: read`.
- Document the new flow (label + re-run) in CONTRIBUTING.md.

Release integration is unchanged: `release-tag.yml` and `release-dev.yml`
continue to call `e2e-test.yml` directly on trusted refs (main / tags).

Signed-off-by: Piotr Mlocek &lt;pmlocek@nvidia.com&gt;
diff --git a/.github/actions/pr-gate/action.yml b/.github/actions/pr-gate/action.yml
@@ -0,0 +1,56 @@
+name: PR Gate
+description: >
+  Resolve PR metadata for a `pull-request/<N>` push from copy-pr-bot and decide
+  whether the workflow should run. Sets `should-run=true` only when the pushed
+  SHA still matches the PR head SHA and the PR carries the required label. For
+  non-`push` events (e.g. `workflow_dispatch`), always sets `should-run=true`.
+
+inputs:
+  required-label:
+    description: PR label required to enable the run (e.g. "test:e2e").
+    required: true
+
+outputs:
+  should-run:
+    description: "true if the workflow should proceed, false otherwise"
+    value: ${{ steps.gate.outputs.should_run }}
+
+runs:
+  using: composite
+  steps:
+    - id: get_pr_info
+      if: github.event_name == 'push'
+      continue-on-error: true
+      uses: nv-gha-runners/get-pr-info@main
+
+    - id: gate
+      shell: bash
+      env:
+        EVENT_NAME: ${{ github.event_name }}
+        GITHUB_SHA_VALUE: ${{ github.sha }}
+        GET_PR_INFO_OUTCOME: ${{ steps.get_pr_info.outcome }}
+        PR_INFO: ${{ steps.get_pr_info.outputs.pr-info }}
+        REQUIRED_LABEL: ${{ inputs.required-label }}
+      run: |
+        if [ "$EVENT_NAME" != "push" ]; then
+          echo "should_run=true" >> "$GITHUB_OUTPUT"
+          exit 0
+        fi
+
+        if [ "$GET_PR_INFO_OUTCOME" != "success" ]; then
+          echo "should_run=false" >> "$GITHUB_OUTPUT"
+          exit 0
+        fi
+
+        head_sha="$(jq -r '.head.sha' <<< "$PR_INFO")"
+        has_label="$(jq -r --arg L "$REQUIRED_LABEL" '[.labels[].name] | index($L) != null' <<< "$PR_INFO")"
+
+        # Only trust copied pull-request/* pushes that still match the PR head
+        # SHA and carry the required label.
+        if [ "$head_sha" = "$GITHUB_SHA_VALUE" ] && [ "$has_label" = "true" ]; then
+          should_run=true
+        else
+          should_run=false
+        fi
+
+        echo "should_run=$should_run" >> "$GITHUB_OUTPUT"
diff --git a/.github/workflows/branch-e2e.yml b/.github/workflows/branch-e2e.yml
@@ -1,32 +1,59 @@
 name: Branch E2E Checks
 
 on:
-  pull_request:
-    types: [opened, synchronize, reopened, labeled]
+  push:
+    branches:
+      - "pull-request/[0-9]+"
+  workflow_dispatch: {}
 
-permissions:
-  contents: read
-  packages: write
+permissions: {}
 
 jobs:
+  pr_metadata:
+    name: Resolve PR metadata
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+    outputs:
+      should_run: ${{ steps.gate.outputs.should-run }}
+    steps:
+      - uses: actions/checkout@v4
+      - id: gate
+        uses: ./.github/actions/pr-gate
+        with:
+          required-label: test:e2e
+
   build-gateway:
-    if: contains(github.event.pull_request.labels.*.name, 'test:e2e')
+    needs: [pr_metadata]
+    if: needs.pr_metadata.outputs.should_run == 'true'
+    permissions:
+      contents: read
+      packages: write
     uses: ./.github/workflows/docker-build.yml
     with:
       component: gateway
       platform: linux/arm64
       runner: build-arm64
 
   build-cluster:
-    if: contains(github.event.pull_request.labels.*.name, 'test:e2e')
+    needs: [pr_metadata]
+    if: needs.pr_metadata.outputs.should_run == 'true'
+    permissions:
+      contents: read
+      packages: write
     uses: ./.github/workflows/docker-build.yml
     with:
       component: cluster
       platform: linux/arm64
       runner: build-arm64
 
   e2e:
-    needs: [build-gateway, build-cluster]
+    needs: [pr_metadata, build-gateway, build-cluster]
+    if: needs.pr_metadata.outputs.should_run == 'true'
+    permissions:
+      contents: read
+      packages: read
     uses: ./.github/workflows/e2e-test.yml
     with:
       image-tag: ${{ github.sha }}
diff --git a/.github/workflows/test-gpu.yml b/.github/workflows/test-gpu.yml
@@ -7,71 +7,50 @@ on:
   workflow_dispatch: {}
   # Add `schedule:` here when we want nightly coverage from the same workflow.
 
-permissions:
-  contents: read
-  pull-requests: read
-  packages: write
+permissions: {}
 
 jobs:
   pr_metadata:
     name: Resolve PR metadata
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
     outputs:
-      should_run: ${{ steps.gate.outputs.should_run }}
+      should_run: ${{ steps.gate.outputs.should-run }}
     steps:
-      - id: get_pr_info
-        if: github.event_name == 'push'
-        continue-on-error: true
-        uses: nv-gha-runners/get-pr-info@main
-
+      - uses: actions/checkout@v4
       - id: gate
-        shell: bash
-        env:
-          EVENT_NAME: ${{ github.event_name }}
-          GITHUB_SHA_VALUE: ${{ github.sha }}
-          GET_PR_INFO_OUTCOME: ${{ steps.get_pr_info.outcome }}
-          PR_INFO: ${{ steps.get_pr_info.outputs.pr-info }}
-        run: |
-          if [ "$EVENT_NAME" != "push" ]; then
-            echo "should_run=true" >> "$GITHUB_OUTPUT"
-            exit 0
-          fi
-
-          if [ "$GET_PR_INFO_OUTCOME" != "success" ]; then
-            echo "should_run=false" >> "$GITHUB_OUTPUT"
-            exit 0
-          fi
-
-          head_sha="$(jq -r '.head.sha' <<< "$PR_INFO")"
-          has_gpu_label="$(jq -r '[.labels[].name] | index("test:e2e-gpu") != null' <<< "$PR_INFO")"
-
-          # Only trust copied pull-request/* pushes that still match the PR head SHA
-          # and are explicitly labeled for GPU coverage.
-          if [ "$head_sha" = "$GITHUB_SHA_VALUE" ] && [ "$has_gpu_label" = "true" ]; then
-            should_run=true
-          else
-            should_run=false
-          fi
-
-          echo "should_run=$should_run" >> "$GITHUB_OUTPUT"
+        uses: ./.github/actions/pr-gate
+        with:
+          required-label: test:e2e-gpu
 
   build-gateway:
     needs: [pr_metadata]
     if: needs.pr_metadata.outputs.should_run == 'true'
+    permissions:
+      contents: read
+      packages: write
     uses: ./.github/workflows/docker-build.yml
     with:
       component: gateway
 
   build-cluster:
     needs: [pr_metadata]
     if: needs.pr_metadata.outputs.should_run == 'true'
+    permissions:
+      contents: read
+      packages: write
     uses: ./.github/workflows/docker-build.yml
     with:
       component: cluster
 
   e2e-gpu:
     needs: [pr_metadata, build-gateway, build-cluster]
     if: needs.pr_metadata.outputs.should_run == 'true'
+    permissions:
+      contents: read
+      packages: read
     uses: ./.github/workflows/e2e-gpu-test.yaml
     with:
       image-tag: ${{ github.sha }}
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -254,6 +254,31 @@ See [docs/CONTRIBUTING.mdx](docs/CONTRIBUTING.mdx) for the current docs authorin
 3. Run `mise run ci` to verify.
 4. Open a PR using the `create-github-pr` skill or manually following the [PR template](.github/PULL_REQUEST_TEMPLATE.md).
 
+### CI Lanes
+
+Most CI runs automatically on every PR push (lint, unit tests, docs validation). Expensive lanes that need self-hosted runners — **Branch E2E Checks** and **GPU Test** — are gated to protect those runners from untrusted code.
+
+Both lanes run against PR code only after it has been mirrored to a `pull-request/<N>` branch in this repository by [`copy-pr-bot`](https://docs.gha-runners.nvidia.com/platform/apps/copy-pr-bot/). They also require an explicit label on the PR:
+
+| Lane                 | Label          | Runner           |
+| -------------------- | -------------- | ---------------- |
+| Branch E2E Checks    | `test:e2e`     | `build-arm64`    |
+| GPU Test             | `test:e2e-gpu` | Self-hosted GPU  |
+
+**Trusted PRs** (org members, vouched contributors with signed commits) are mirrored automatically when marked ready-for-review.
+
+**Untrusted PRs** (unvouched users, unsigned commits) need a vetter to comment `/ok to test <SHA>` on the PR. `copy-pr-bot` mirrors the code once the vetter approves.
+
+The workflow re-checks the label and head SHA on every `pull-request/<N>` push. A maintainer typically:
+
+1. Reviews the PR for safety.
+2. Applies `test:e2e` (and/or `test:e2e-gpu`).
+3. Triggers the run:
+   - If the label was applied **before** `copy-pr-bot` mirrored the code, the push already ran the workflow and it will now pick up the label automatically on the next commit.
+   - If `copy-pr-bot` already mirrored and the initial run showed `should_run=false`, re-run that workflow from the Actions UI (or `gh run rerun <run-id>`). The gate fetches live PR metadata, sees the label, and proceeds.
+
+Release builds (`Release Tag`, `Release Dev`) run the same E2E reusable workflow on `main` / tag pushes — those refs are inherently trusted, so they do not go through `copy-pr-bot`.
+
 ### Commit Messages
 
 This project uses [Conventional Commits](https://www.conventionalcommits.org/). All commit messages must follow the format:
