ci(e2e): gate final-main fanout on base-image publication

[apurvvkumaria]

Summary

Final-main E2E previously fanned out even when the newest applicable base-image publication was missing, partial, or failed. This change adds a trusted, fail-closed preflight that proves all required publishers succeeded before matrix generation, while preserving the controller-selected PR path without checking out PR code. It also validates protected approval runs from immutable workflow identity instead of the Actions REST API's dynamic evaluated run-name.

Related Issue

Fixes #7372

Changes

• Add a dependency-free publication verifier that derives publisher inputs from the checked-in workflow, resolves the applicable first-parent commit, bounded-polls paginated GitHub evidence, validates workflow/run/job provenance across rerun attempts, and reconfirms the selected run.
• Add a least-privilege base-image-publication job before generate-matrix; trusted main schedule/manual runs perform the check, controller-selected PR dispatches bypass it before checkout, and invalid invocation modes fail closed.
• Validate protected approval runs by exact workflow path, trusted workflow SHA, run ID, event, branch, status, first attempt, and canonical URL without trusting mutable run-name text.
• Add focused behavioral and workflow-boundary coverage for pagination, retries, batched pushes, merge history, partial/failed evidence, diagnostic context, controller bypass, approval identity, and trust-boundary mutations.
• Keep this change independent of test(e2e): add semantic live progress phases #7100's progress artifacts and perf(ci): shorten main and E2E feedback loops #7262's matrix timeout; preserve those adjacent lines if either PR lands first.
• Scope this fix to publication sequencing. Strict digest pinning and removal of downstream mutable latest fallback remain follow-up work.

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 changes internal GitHub Actions sequencing and provenance validation only; CLI, configuration, runtime, installation, and user-facing image behavior are unchanged.
• 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: A final fail-closed trust-boundary review found one diagnostic-context gap, which was fixed and regression-tested; no other blocking findings remained.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Documentation Writer Review

• Documentation writer subagent reviewed the completed implementation
• Result: no-docs-needed
• Evidence: The change adds an automatic internal E2E publication-provenance gate without changing CLI, configuration, runtime, installation, or user-facing image behavior.
• Agent: Codex Desktop
• PR: ci(e2e): gate final-main fanout on base-image publication #7373

DGX Station Hardware Evidence

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

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 — command/result or justification: npx vitest run --project e2e-support test/e2e/support/base-image-publication.test.ts test/e2e/support/base-image-publication-workflow-boundary.test.ts test/e2e/support/e2e-workflow.test.ts — 95 passed; the seven focused PR-gate identity/lifecycle files also passed 123 tests.
• Applicable broad gate passed — npm run checks, npm run typecheck:cli, and npx prek run --from-ref origin/main --to-ref HEAD passed.
• 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: Apurv Kumaria akumaria@nvidia.com

Summary by CodeRabbit

• New Features
  • Added a base-image publication verification gate that determines whether publication evidence is required before running E2E workflows.
  • Updated E2E matrix generation and PR E2E reporting to wait for this gate’s result.
  • Strengthened the E2E workflow boundary validation and approval authorization checks to rely on stable, trusted attributes.
• Tests
  • Added end-to-end boundary coverage for the base-image publication policy, including classifier behavior and drift detection.
  • Added evidence validation tests for workflow/run selection, publisher job evidence rules, pagination safety, and deterministic polling/timeout behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 0e4eb5ec-c364-4492-973c-f0348603f097

📥 Commits

Reviewing files that changed from the base of the PR and between dcadfa8 and 7067684.

📒 Files selected for processing (3)

• test/pr-e2e-gate-fork-skip.test.ts
• test/pr-e2e-gate-internal-approval.test.ts
• tools/e2e/pr-e2e-gate.mts

---

📝 Walkthrough

Walkthrough

Adds a trusted base-image publication preflight for selected E2E runs. The verifier derives the applicable source commit, polls and validates GitHub publication evidence, and blocks matrix generation until required publisher jobs succeed.

Changes

Base-image publication gate

Layer / File(s)	Summary
Hardened workflow boundary tools/e2e/operations-workflow-boundary.mts, test/e2e/support/base-image-publication-workflow-boundary.test.ts	Adds strict classifier and workflow-structure validation for the publication job, trusted checkout, pinned verifier, permissions, and matrix dependency.
Trusted source history resolution tools/e2e/base-image-publication.mts, test/e2e/support/base-image-publication.test.ts	Extracts safe base-image push paths and resolves the applicable first-parent commit from the exact checkout, including merge-commit and fail-closed validation tests.
Publication evidence polling tools/e2e/base-image-publication.mts, test/e2e/support/base-image-publication.test.ts	Validates workflow identity and runs, selects the trusted publication run, checks publisher attempts, handles pagination and retries, and polls until success or timeout.
E2E fanout wiring .github/workflows/e2e.yaml	Adds the publication gate, makes generate-matrix depend on it, and includes it in PR result reporting prerequisites.
Approval workflow identity binding tools/e2e/pr-e2e-gate.mts, test/pr-e2e-gate-*.test.ts	Binds approval validation to trusted workflow attributes instead of the mutable workflow display name, with updated fixtures and cases.

Estimated code review effort: 5 (Critical) | ~120 minutes

Suggested labels: chore, integration: dcode

Suggested reviewers: cv, prekshivyas

Sequence Diagram(s)

sequenceDiagram
  participant E2EWorkflow
  participant BaseImagePublication
  participant Git
  participant GitHub
  participant PublisherJobs
  E2EWorkflow->>BaseImagePublication: run trusted publication preflight
  BaseImagePublication->>Git: resolve applicable first-parent SHA
  BaseImagePublication->>GitHub: poll publication workflow runs
  GitHub-->>BaseImagePublication: selected run status
  BaseImagePublication->>PublisherJobs: validate required publisher attempts
  PublisherJobs-->>BaseImagePublication: successful evidence
  BaseImagePublication-->>E2EWorkflow: gate success
  E2EWorkflow->>E2EWorkflow: generate E2E matrix

Loading

🚥 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
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: gating final-main E2E fanout on base-image publication.
Linked Issues check	✅ Passed	The workflow and verifier changes match #7372 by gating matrix fanout on validated base-image publication with bounded polling and fail-closed behavior.
Out of Scope Changes check	✅ Passed	The additional controller-auth and test updates support the new gate and do not appear unrelated to the linked objectives.

✨ 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/7372-base-image-publication-gate

---

_{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 7067684 in the codex/7372-base-imag... branch remains at 96%, unchanged from commit 670d32e in the main branch.

---

_{Updated July 22, 2026 23:55 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 · 0 warnings · 0 suggestions
• Model comparison: normalized findings match; normalized E2E selections differ; severity counts match.

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

1 optional E2E recommendation

• e2e-all

Workflow run details

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

[coderabbitai]

Actionable comments posted: 1

🤖 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.

Inline comments:
In `@test/e2e/support/base-image-publication.test.ts`:
- Around line 196-203: Remove conditional branches from the fake Git callbacks
in test/e2e/support/base-image-publication.test.ts at lines 196-203 and 270-273
by using a command-to-response lookup map that preserves each existing response.
In test/e2e/support/base-image-publication-workflow-boundary.test.ts at lines
44-78, replace the guard clauses in gateSteps and runClassifier with a
branch-free assertion helper accepted by the guardrail.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 78776acb-c192-4cb7-b330-652b798a954f

📥 Commits

Reviewing files that changed from the base of the PR and between 6e70994 and be688d7.

📒 Files selected for processing (5)

• .github/workflows/e2e.yaml
• test/e2e/support/base-image-publication-workflow-boundary.test.ts
• test/e2e/support/base-image-publication.test.ts
• tools/e2e/base-image-publication.mts
• tools/e2e/operations-workflow-boundary.mts

[prekshivyas]

Reviewed exact head dcadfa8 against base 3ef2ca8.

Security verdict: PASS, with no findings across all 5 changed files.

• Secrets and credentials: PASS
• Input validation and sanitization: PASS
• Authentication and authorization: PASS
• Dependencies and third-party libraries: PASS
• Error handling and logging: PASS
• Cryptography and data protection: PASS
• Configuration and security headers: PASS
• Security testing: PASS
• Holistic security posture: PASS

The gate fails closed, binds evidence to trusted main first-parent history and exact workflow/run/job provenance, uses read-only permissions, and revalidates the selected run after job inspection. The advisor warning about classifier duplication is covered by the existing exact whole-job boundary comparison and mutation tests; an external checked-out script would weaken the required pre-checkout boundary.

Validation: 3 focused E2E-support files passed, 97/97 tests. Live GitHub API response shapes also match the verifier contract. The current E2E red is a maintainer-authorization timeout; exact-SHA credentialed E2E remains required.

[cv]

Re-reviewed exact head 10a2123 against current main 1bb15a0. Both base refreshes are Verified, conflict-free, and leave the five-file effective publication-gate diff unchanged. The merged documentation-receipt workflow does not alter this PR's runtime semantics; prior product-scope and nine-category security PASS conclusions remain valid. Awaiting fresh GitHub-hosted gates.

[apurvvkumaria]

The held exact-SHA validation run 29964500642 is now terminal. It did not expose an approval-gate assertion failure:

• Hermes security-posture job 89073362734 lost hosted runner 1021276370 at 23:50:13 UTC.
• cloud-onboard job 89073362742 lost separate hosted runner 1021276371 at 23:50:11 UTC.
• Both failed after about 51 minutes, before their 75/70-minute workflow timeouts. GitHub reported lost server communication; each live step remained in_progress with artifact and cleanup steps pending, and neither job produced a log blob.

The near-simultaneous loss of two separate standard runners is infrastructure-loss evidence rather than a product assertion. I preserved that run until it was terminal, then pushed 70676843f, which fixes the independent approval-run identity validation defect without rerunning or cancelling this evidence.