ci(e2e): delegate protected gate approvals

[prekshivyas]

Summary

Internal PRs that change credential-bearing E2E trust boundaries now request an exact-SHA protected-environment review automatically after ordinary CI. Repository-configured E2E reviewers can approve that environment without merge rights, while fork PR code still never receives repository secrets.

Required Repository Configuration

Before merging or enabling this workflow, a repository administrator must:

1. Create the environment approve-credentialed-e2e-for-internal-pr.
2. Configure one or more required reviewers. Prefer an organization team such as nemoclaw-e2e-approvers; members need repository read access but do not need merge rights. Individuals can also be listed directly.
3. Enable Prevent self-review.
4. Disable administrator bypass.
5. Restrict the environment to protected main.
6. Do not add environment secrets, variables, or custom protection apps.

Only one configured reviewer is required to approve a run. The approval must cover the exact test plan. Complete this configuration before merging or enabling the workflow.

Changes

• Add approve-credentialed-e2e-for-internal-pr as a protected, non-deployment environment gate before internal credentialed E2E dispatch.
• Bind approval to the first trusted controller attempt, exact workflow SHA, PR head SHA, base SHA, deterministic plan, and one approval naming only the expected environment.
• Treat protected-environment reviewer configuration as the delegated authority for both internal execution approval and fork skip approval; retain maintain or admin checks on both manual fallback operations.
• Fail closed without dispatch when approval history, environment configuration, run identity, PR identity, or the live revision does not match.
• Document rollout requirements: required reviewer allowlists, Prevent self-review, protected main, no environment secrets, variables, or custom protection apps, and exact plan review.
• Keep the existing manual run-control-plane and approve-fork-e2e-skip operations as maintainer fallbacks.

This intentionally excludes the feedback-loop and observer-removal changes in #7262. Both PRs touch the gate lifecycle, so whichever merges second will require security-sensitive conflict resolution rather than an automatic merge.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification:
• Tests not applicable — justification:
• Docs updated for user-facing behavior changes
• Docs not applicable — justification: this is a maintainer-only repository E2E authorization operation; test/e2e/README.md documents the operational change and no shipped user surface changes.
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification: pending maintainer security review.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit: not applicable
• Station profile/scenario: not applicable
• Result: not applicable
• Supporting evidence: not applicable

Verification

• PR description includes a Signed-off-by: line and every commit appears as Verified in GitHub
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run check:diff passed when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — npx vitest run test/pr-e2e-gate-command.test.ts test/pr-e2e-gate-workflow.test.ts test/pr-e2e-gate-fork-skip.test.ts test/pr-e2e-gate-internal-approval.test.ts test/pr-e2e-gate-retry-history.test.ts test/pr-e2e-required.test.ts (94 passed); npm run typecheck:cli; npm run test-size:check.
• Applicable broad gate passed — npm test completed with 18,865 passed, 201 skipped, and 20 failures in untouched local macOS/tooling-dependent tests. Failures include /private/var path normalization, missing GNU timeout and stat -c, Bash-version assumptions, Docker timing/memory, Python build tooling, and unrelated timeouts. Approval-specific tests are green; CI must provide the authoritative Linux broad result.
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs builds without warnings (doc changes only)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Prekshi Vyas prekshiv@nvidia.com

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR adds protected-environment approval handling for internal credentialed E2E runs, including controller commands, workflow orchestration, evidence finalization, reviewer-based authorization, targeted cancellation, tests, and updated operational documentation.

Changes

Internal E2E approval

Layer / File(s)	Summary
Approval contracts and controller flow tools/e2e/pr-e2e-gate.mts	Adds start-approved-control-plane, validates protected approvals, emits approval outputs, and dispatches authorized control-plane runs.
Workflow orchestration and cancellation .github/workflows/pr-e2e-gate.yaml, tools/e2e/pr-e2e-gate.mts	Adds coordinator approval outputs, the gated approve-internal-e2e job, evidence finalization, cleanup, and targeted superseded-check cancellation.
Approval and lifecycle tests test/pr-e2e-gate-command.test.ts, test/pr-e2e-gate-internal-approval.test.ts, test/pr-e2e-gate-lifecycle.test.ts, test/pr-e2e-gate-workflow.test.ts	Covers command parsing, protected approval dispatch, fail-closed behavior, workflow wiring, and superseded-check cancellation.
Regression coverage and documentation test/pr-e2e-gate-*.test.ts, test/pr-e2e-required.test.ts, test/e2e/README.md	Updates reviewer-based authorization expectations, approval setup guidance, retry behavior, and synchronization documentation.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Coordinator
  participant ApproveInternalE2E
  participant Controller
  participant GitHub
  Coordinator->>ApproveInternalE2E: pass approval PR and SHA outputs
  ApproveInternalE2E->>Controller: run start-approved-control-plane
  Controller->>GitHub: validate workflow run and environment approval
  Controller->>GitHub: dispatch approved E2E run
  ApproveInternalE2E->>GitHub: wait for and verify evidence

Loading

Possibly related PRs

• NVIDIA/NemoClaw#6810: Related protected-environment approval command and workflow plumbing.
• NVIDIA/NemoClaw#6914: Related control-plane authorization check-state handling.
• NVIDIA/NemoClaw#7262: Related PR E2E gate check identity changes.

Suggested labels: area: ci, area: e2e, area: security

Suggested reviewers: cv

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: delegating protected E2E gate approvals.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/delegate-e2e-approval

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit 8031a94 in the codex/delegate-e2e-a... branch remains at 96%, unchanged from commit 5087eb4 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 8031a94 in the codex/delegate-e2e-a... branch remains at 80%, unchanged from commit 7be3ef7 in the main branch.

Show a code coverage summary of the most impacted files.

File	main 7be3ef7	codex/delegate-e2e-a... 8031a94	+/-
src/lib/inferen...lama/process.ts	100%	50%	-50%
src/lib/domain/.../connect-env.ts	97%	89%	-8%
src/lib/inferen...er-lifecycle.ts	71%	65%	-6%
src/lib/platform.ts	89%	84%	-5%
src/lib/messagi...nnels/policy.ts	100%	100%	0%
src/lib/sandbox...rce-identity.ts	88%	88%	0%
src/lib/securit...ntial-filter.ts	93%	93%	0%
src/lib/trace.ts	94%	94%	0%
src/lib/tunnel/services.ts	73%	73%	0%
src/lib/state/g...way-registry.ts	94%	95%	+1%

---

_{Updated July 22, 2026 02:57 UTC}

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / high confidence
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions
Status: No actionable findings remain in the canonical review ledger.

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 5 warnings · 2 suggestions
• Model comparison: normalized findings differ; normalized E2E selections differ; Nemotron reported the same number of blockers, 5 more warnings, 2 more suggestions.

Nemotron output stays in workflow artifacts and does not change the assessment above.

E2E guidance

Advisory only. E2E / PR Gate selects and runs jobs independently.

Recommended E2E: cloud-onboard, credential-sanitization, security-posture

Workflow run details

This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge.

[coderabbitai]

🧹 Nitpick comments (1)

.github/workflows/pr-e2e-gate.yaml (1)

335-337: 🩺 Stability & Availability | 🔵 Trivial

Consider cancel-in-progress: false here, mirroring the coordinate job's rationale.

coordinate's concurrency group deliberately uses cancel-in-progress: false so the outgoing run can observe cancellation and close its own check. approve-internal-e2e is gated by the protected environment before any step runs (including "Checkout controller"), so if a newer push cancels it via cancel-in-progress: true while it's still "Waiting" for reviewer approval, no step — not even the always() "Close incomplete approved check" step — ever executes. The check for that stale head/base SHA pair is left permanently "in_progress" with the authorization title. Blast radius is limited (checks are scoped to the exact head/base SHA pair, so it won't block the required check for the PR's current head), but it does leave dangling pending-approval checks on abandoned commits that require no cleanup path.

If the intent is to let a new push immediately supersede the pending approval wait (rather than queue behind it for up to timeout-minutes: 180), that's a reasonable tradeoff — but it's worth confirming this was a deliberate choice given the explicit contrast with the sibling job's documented reasoning.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/pr-e2e-gate.yaml around lines 335 - 337, Update the
approve-internal-e2e concurrency configuration to use cancel-in-progress: false,
matching the coordinate job’s behavior and allowing the pending
protected-environment run to execute its cleanup steps. Keep the existing
concurrency group unchanged.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In @.github/workflows/pr-e2e-gate.yaml:
- Around line 335-337: Update the approve-internal-e2e concurrency configuration
to use cancel-in-progress: false, matching the coordinate job’s behavior and
allowing the pending protected-environment run to execute its cleanup steps.
Keep the existing concurrency group unchanged.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 61e6c3fd-d422-432c-a19f-a06b55aabada

📥 Commits

Reviewing files that changed from the base of the PR and between 426af01 and 1cb71f1.

📒 Files selected for processing (9)

• .github/workflows/pr-e2e-gate.yaml
• test/e2e/README.md
• test/pr-e2e-gate-command.test.ts
• test/pr-e2e-gate-fork-skip.test.ts
• test/pr-e2e-gate-internal-approval.test.ts
• test/pr-e2e-gate-retry-history.test.ts
• test/pr-e2e-gate-workflow.test.ts
• test/pr-e2e-required.test.ts
• tools/e2e/pr-e2e-gate.mts

[apurvvkumaria]

Repository-configuration follow-up: the required rollout configuration in this PR was not completed. The live environment API currently reports:

• protection_rules: [] (no required reviewers);
• can_admins_bypass: true;
• deployment_branch_policy: null (no protected-main restriction); and
• zero environment secrets and variables (this part is correct).

This is now fail-closing every protected internal E2E request. #7492 approval run 30126807957, #7493 run 30119974452, and #7494 run 30124567776 all auto-started instead of showing Review deployments, then failed with No required-reviewer approval was recorded. Their coordination checks remain pending.

A repository administrator needs to complete this PR's documented setup: add one or more required reviewers, enable prevent-self-review, disable admin bypass, restrict deployment to protected main, and keep the environment free of secrets, variables, and custom protection apps. The failed runs cannot be approved retroactively; after configuration, each PR needs a new head/fresh CI and an authorized reviewer must approve the new deployment request.

@prekshivyas @cv @cjagwani — please coordinate the reviewer/team selection with a repository admin. The manual maintainer fallback can unblock one PR, but it does not repair this repository-wide gate.