runtime live e2e: add pr trigger and CI-E2E gate

Author: clkao

.github/workflows/runtime-live-e2e.yml

@@ -1,6 +1,7 @@
 name: Runtime Live E2E
 
 on:
+  pull_request:
   workflow_dispatch:
     inputs:
       pr_number:
@@ -15,9 +16,12 @@ permissions:
 jobs:
   claude-live:
     runs-on: ubuntu-latest
+    environment: CI-E2E
     env:
       DISABLE_AUTOUPDATER: "1"
-      PR_NUMBER: ${{ inputs.pr_number }}
+      TRIGGER_SOURCE: ${{ github.event_name }}
+      PR_NUMBER: ${{ github.event.pull_request.number }}
+      DISPATCH_PR_NUMBER: ${{ inputs.pr_number }}
       ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
     steps:
       - name: Check required secret
@@ -31,9 +35,21 @@ jobs:
         uses: actions/github-script@v7
         with:
           script: |
-            const prNumber = Number(process.env.PR_NUMBER);
+            const triggerSource = process.env.TRIGGER_SOURCE;
+            let rawPrNumber;
+
+            if (triggerSource === "pull_request") {
+              rawPrNumber = process.env.PR_NUMBER;
+            } else if (triggerSource === "workflow_dispatch") {
+              rawPrNumber = process.env.DISPATCH_PR_NUMBER;
+            } else {
+              core.setFailed(`Unsupported trigger source: ${JSON.stringify(triggerSource)}`);
+              return;
+            }
+
+            const prNumber = Number(rawPrNumber);
             if (!Number.isInteger(prNumber) || prNumber <= 0) {
-              core.setFailed(`workflow_dispatch input pr_number must be a positive integer, got ${JSON.stringify(process.env.PR_NUMBER)}`);
+              core.setFailed(`${triggerSource} PR number must be a positive integer, got ${JSON.stringify(rawPrNumber)}`);
               return;
             }
 
@@ -59,6 +75,7 @@ jobs:
 
             await core.summary
               .addHeading("Runtime Live E2E Provenance")
+              .addRaw(`- Trigger source: ${triggerSource}\n`)
               .addRaw(`- PR number: #${prNumber}\n`)
               .addRaw(`- Tested workflow SHA: \`${context.sha}\`\n`)
               .addRaw(`- Current PR head SHA: \`${pull.head.sha}\`\n`)
@@ -107,8 +124,11 @@ jobs:
 
   codex-live:
     runs-on: ubuntu-latest
+    environment: CI-E2E
     env:
-      PR_NUMBER: ${{ inputs.pr_number }}
+      TRIGGER_SOURCE: ${{ github.event_name }}
+      PR_NUMBER: ${{ github.event.pull_request.number }}
+      DISPATCH_PR_NUMBER: ${{ inputs.pr_number }}
       OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
     steps:
       - name: Check required secret
@@ -122,9 +142,21 @@ jobs:
         uses: actions/github-script@v7
         with:
           script: |
-            const prNumber = Number(process.env.PR_NUMBER);
+            const triggerSource = process.env.TRIGGER_SOURCE;
+            let rawPrNumber;
+
+            if (triggerSource === "pull_request") {
+              rawPrNumber = process.env.PR_NUMBER;
+            } else if (triggerSource === "workflow_dispatch") {
+              rawPrNumber = process.env.DISPATCH_PR_NUMBER;
+            } else {
+              core.setFailed(`Unsupported trigger source: ${JSON.stringify(triggerSource)}`);
+              return;
+            }
+
+            const prNumber = Number(rawPrNumber);
             if (!Number.isInteger(prNumber) || prNumber <= 0) {
-              core.setFailed(`workflow_dispatch input pr_number must be a positive integer, got ${JSON.stringify(process.env.PR_NUMBER)}`);
+              core.setFailed(`${triggerSource} PR number must be a positive integer, got ${JSON.stringify(rawPrNumber)}`);
               return;
             }
 
@@ -150,6 +182,7 @@ jobs:
 
             await core.summary
               .addHeading("Runtime Live E2E Provenance")
+              .addRaw(`- Trigger source: ${triggerSource}\n`)
               .addRaw(`- PR number: #${prNumber}\n`)
               .addRaw(`- Tested workflow SHA: \`${context.sha}\`\n`)
               .addRaw(`- Current PR head SHA: \`${pull.head.sha}\`\n`)

docs/plans/runtime-live-e2e-pr-trigger-and-environment-gate.md

@@ -68,3 +68,22 @@ The summary output should continue to show:
 - Workflow-structure inspection: verify trigger block, environment fields, and provenance logic for both event types. Cost/complexity: low. No E2E required.
 - Focused offline tests: update/add static tests for the PR-trigger and `CI-E2E` environment wiring. Cost/complexity: low-medium. No E2E required.
 - Optional GitHub smoke after merge: open or reuse a PR and confirm the runtime workflow appears on the PR and waits for `CI-E2E` approval before the live jobs run. Cost/complexity: medium. E2E required: yes, but not required to finish implementation in this cycle.
+
+## Stage Report: implementation
+
+- [x] Add `pull_request` triggering while keeping `workflow_dispatch`.
+  `.github/workflows/runtime-live-e2e.yml` now includes both triggers, with `workflow_dispatch` retained for targeted reruns.
+- [x] Add `environment: CI-E2E` to both live jobs.
+  Both `claude-live` and `codex-live` declare the `CI-E2E` environment, which is the approval gate for the live runtime checks.
+- [x] Resolve PR provenance correctly for both trigger paths.
+  The provenance step branches on `github.event_name` and uses `github.event.pull_request.number` for PR runs or `inputs.pr_number` for manual dispatch runs.
+- [x] Update the operator docs for the new PR-native flow and rerun path.
+  `tests/README.md` now explains the pending `CI-E2E` approval flow, the environment-scoped secrets, and the retained manual rerun command.
+- [x] Update offline coverage for the trigger/environment behavior.
+  `tests/test_runtime_live_e2e_workflow.py` now checks the trigger block, job environments, provenance fields, and the README wording.
+- [x] Run focused verification for the edited workflow/docs/test files.
+  `unset CLAUDECODE && uv run tests/test_runtime_live_e2e_workflow.py` is the targeted static check for this change set.
+
+### Summary
+
+Implemented the PR-native live E2E workflow shape with `CI-E2E` approval gating while keeping manual dispatch available for reruns. The workflow now carries event-specific provenance, the operator docs explain the approval flow, and the offline test coverage matches the new wiring.

tests/README.md

@@ -191,11 +191,13 @@ make test-e2e TEST=tests/test_gate_guardrail.py RUNTIME=codex
 uv run tests/test_gate_guardrail.py --runtime codex
 ```
 
-## Manual PR Runtime Live E2E
+## PR Runtime Live E2E
 
-The expensive runtime-backed PR suite lives in `.github/workflows/runtime-live-e2e.yml`. It is a `workflow_dispatch` workflow, not an always-on `pull_request` workflow. A maintainer runs it only after the PR has been approved and the always-on static workflow is already green.
+The expensive runtime-backed PR suite lives in `.github/workflows/runtime-live-e2e.yml`. It now triggers on `pull_request` so the runtime jobs show up on the PR alongside Static CI, and it still supports `workflow_dispatch` for targeted reruns.
 
-Invoke it from the Actions UI on the branch under test, or with:
+GitHub blocks each runtime job behind the `CI-E2E` environment review gate. Until an approved reviewer releases that environment, the job stays pending and cannot access the environment-scoped API keys.
+
+Open a PR and then approve the pending `CI-E2E` deployment to release the live runtime checks. For targeted reruns or branch-local debugging, invoke the workflow manually from Actions or with:
 
 ```bash
 gh workflow run runtime-live-e2e.yml --ref <pr-branch> -f pr_number=<N>
@@ -206,17 +208,18 @@ This workflow runs exactly two jobs:
 - `claude-live`
 - `codex-live`
 
-Required repository secrets:
+Required `CI-E2E` environment secrets:
 
 - `ANTHROPIC_API_KEY` for `claude-live`
 - `OPENAI_API_KEY` for `codex-live`
 
-Each job fails immediately with a clear message if its required secret is missing.
+Each job fails immediately with a clear message if its required secret is missing after the environment is approved.
 
 This workflow is expected to report current live-suite status honestly. If a runtime test fails, the corresponding job stays red; shipping the manual CI wiring does not imply the Claude and Codex suites are already fully green.
 
 Operators should expect each job summary to show the run provenance explicitly:
 
+- Trigger source
 - PR number
 - Tested workflow SHA
 - Current PR head SHA

tests/test_runtime_live_e2e_workflow.py

@@ -2,8 +2,8 @@
 # /// script
 # requires-python = ">=3.10"
 # ///
-# ABOUTME: Static checks for the manual runtime live E2E workflow and its operator docs.
-# ABOUTME: Verifies the workflow stays manual, split into exactly two runtime jobs, and documents provenance/secrets.
+# ABOUTME: Static checks for the runtime live E2E workflow and its operator docs.
+# ABOUTME: Verifies PR/manual triggers, CI-E2E approval gating, and the two runtime jobs.
 
 from __future__ import annotations
 
@@ -34,20 +34,24 @@ def section(text: str, heading: str) -> str:
     return "\n".join(lines)
 
 
-def test_runtime_live_e2e_workflow_exists_and_is_manual_only():
+def test_runtime_live_e2e_workflow_supports_pr_and_manual_triggers():
     text = read_workflow()
 
     assert "workflow_dispatch:" in text
-    assert "pull_request:" not in text
+    assert "pull_request:" in text
     assert "pr_number:" in text
     assert "required: true" in text
 
 
 def test_runtime_live_e2e_workflow_has_exactly_two_runtime_jobs():
     text = read_workflow()
+    claude_section = section(text, "  claude-live")
+    codex_section = section(text, "  codex-live")
 
     assert "\n  claude-live:\n" in text
     assert "\n  codex-live:\n" in text
+    assert "environment: CI-E2E" in claude_section
+    assert "environment: CI-E2E" in codex_section
     assert "path classifier" not in text.lower()
     assert "shard" not in text.lower()
     assert "matrix:" not in text
@@ -91,9 +95,14 @@ def test_runtime_live_e2e_workflow_lists_the_expected_commands_and_provenance_fi
         "same-repo",
         "fork",
         "Approval context",
+        "Trigger source",
     ):
         assert field in text
 
+    assert "github.event.pull_request.number" in text
+    assert "inputs.pr_number" in text
+    assert "TRIGGER_SOURCE" in text
+    assert "DISPATCH_PR_NUMBER" in text
     assert "set -euo pipefail" in text
     assert "continue-on-error" not in text
     assert "|| true" not in text
@@ -104,7 +113,8 @@ def test_tests_readme_documents_runtime_live_e2e_workflow():
 
     assert "runtime-live-e2e.yml" in text
     assert "workflow_dispatch" in text
-    assert "after the PR has been approved" in text
+    assert "pull_request" in text
+    assert "CI-E2E" in text
     assert "claude-live" in text
     assert "codex-live" in text
     assert "ANTHROPIC_API_KEY" in text
@@ -114,4 +124,6 @@ def test_tests_readme_documents_runtime_live_e2e_workflow():
     assert "Current PR head SHA" in text
     assert "same-repo vs fork" in text
     assert "approval/reviewer context" in text
+    assert "Trigger source" in text
     assert "job stays red" in text
+    assert "pending `CI-E2E` deployment" in text