ci(images): publish validated managed OCI images

[ericksoa]

Summary

Publish runnable, agent-complete OCI images from trusted CI so later onboarding can consume immutable digests without building Dockerfiles on the user host. The publisher keeps image construction in the existing reviewed Dockerfiles, binds every final image to the exact base digest produced in the same workflow run, and validates the public runtime contract before creating consumer aliases. This is stack PR 2 for #7744.

Related Issue

Related to #7744

Changes

• Export exact, same-run base-image contracts for OpenClaw, Hermes, and Deep Agents Code.
• Add a reusable publisher for the three complete linux/amd64 managed images with SBOM and maximum provenance attestations.
• Push by digest first, require an anonymous exact-digest pull, validate entrypoint, command, labels, agent binary, blueprint, node-tar inventory, and absence of a baked corporate CA, then promote only full-source-SHA and release aliases.
• Record exact final/base digests, source revision, platform, aliases, and run identity in per-agent contract artifacts.
• Expand the protected base-image publication gate across reviewed managed-image input families while retaining fail-closed path validation and first-parent provenance.
• Scope workflow concurrency by ref and prevent release-tag publication from being cancelled by unrelated runs.
• Bootstrap note: a newly created GHCR package is private by default. Its first trusted run intentionally stops after the digest push and before alias promotion until the package is made public; rerunning then proves anonymous pullability before promotion.

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 CI-only slice publishes artifacts but does not yet change CLI behavior, onboarding, runtime selection, configuration, or a supported user workflow.
• 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: Maintainer-directed image supply-chain groundwork under [Epic] Support native Podman with buildless managed onboarding #7744; exact-digest handoff, anonymous pull, fail-before-promotion ordering, immutable actions, and first-parent publication provenance are covered by focused workflow tests and actionlint.
• 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 changes
• Result: no-docs-needed
• Evidence: At 061e44f571db, this slice only publishes internal managed-image artifacts and validation contracts. It does not activate CLI or runtime selection, and existing Dockerfile-based onboarding documentation remains accurate until a later slice consumes these images. The exact-head review also replaced an ambiguous test title with the explicit release-tag non-cancellation invariant.
• Agent: Codex Desktop

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 validate:pr passed after refreshing origin/main
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — command/result or justification: npx vitest run --project integration test/managed-image-publication-workflow.test.ts and npx vitest run --project e2e-support test/e2e/support/base-image-publication.test.ts passed 46 tests on the refreshed stack head. npm run validate:pr also passed.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/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: Aaron Erickson aerickson@nvidia.com

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR adds contract-based managed-image publication for three agents across two architectures, including immutable builds, validation, aggregate promotion barriers, alias verification, artifact retention, and reviewed path-glob expansion.

Changes

Managed image publication

Layer / File(s)	Summary
Base inputs and contracts .github/workflows/base-image.yaml, tools/e2e/base-image-publication.mts, test/e2e/support/base-image-publication.test.ts	Base-image triggers and concurrency are updated; reviewed globs expand through first-parent history; Hermes, Deep Agents Code, and OpenClaw emit validated managed-base contracts.
Managed image candidates .github/workflows/managed-images.yaml, test/helpers/managed-image-publication-barrier.ts, test/managed-image-publication-workflow.test.ts	A six-lane matrix builds managed images by immutable digest, validates image contents and identity, and exports candidate contracts with attestations.
Promotion barrier and final contracts .github/workflows/managed-images.yaml, test/helpers/managed-image-publication-barrier.ts, test/managed-image-publication-workflow.test.ts	Promotion validates all candidates, stages cohort aliases, verifies OpenClaw pointers, and uploads final platform and cohort contracts.

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

Sequence Diagram(s)

sequenceDiagram
  participant BaseImageWorkflow
  participant ManagedImagesWorkflow
  participant GHCR
  BaseImageWorkflow->>ManagedImagesWorkflow: provide managed-base contract artifacts
  ManagedImagesWorkflow->>GHCR: build and push digest-only images
  ManagedImagesWorkflow->>ManagedImagesWorkflow: validate six candidate contracts
  ManagedImagesWorkflow->>GHCR: stage cohort aliases
  ManagedImagesWorkflow->>GHCR: publish verified OpenClaw aliases

Loading

Possibly related issues

• [Epic] Support native Podman with buildless managed onboarding #7744 — Covers immutable multi-architecture managed-image publication for OpenClaw, Hermes, and Deep Agents Code.

Possibly related PRs

• NVIDIA/NemoClaw#6899 — Modifies the same base-image lanes and publication workflow.
• NVIDIA/NemoClaw#7844 — Changes the same manifest digest handling and validation paths.
• NVIDIA/NemoClaw#7864 — Updates related per-architecture digest and manifest validation logic.

Suggested labels: area: ci, area: packaging, area: architecture

Suggested reviewers: cv, jyaunches, prekshivyas

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 12.50% 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 clearly summarizes the main change: publishing validated managed OCI images in CI.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/publish-complete-managed-images

---

_{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 061e44f in the feat/publish-complet... branch remains at 96%, unchanged from commit 25de83d in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 061e44f in the feat/publish-complet... branch remains at 81%, unchanged from commit 25de83d in the main branch.

Show a code coverage summary of the most impacted files.

File	main 25de83d	feat/publish-complet... 061e44f	+/-
src/lib/onboard...ndbox-create.ts	83%	33%	-50%
src/lib/onboard...-create-plan.ts	88%	75%	-13%
src/lib/onboard...ndbox-create.ts	91%	83%	-8%
src/lib/sandbox...rce-identity.ts	88%	88%	0%

---

_{Updated July 30, 2026 18:07 UTC}

[github-actions]

PR Review Advisor — No blocking findings reported

Advisor assessment: No blocking advisor findings reported
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions

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-inference, cloud-onboard, security-posture

Workflow run details

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

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[coderabbitai]

🧹 Nitpick comments (6)

.github/workflows/base-image.yaml (2)

549-609: 📐 Maintainability & Code Quality | 🔵 Trivial | 🏗️ Heavy lift

Three byte-identical contract blocks differ only by agent name.

The ~60-line contract generation plus jq -e invariant block is copied verbatim for Hermes, Deep Agents Code, and OpenClaw, with agent: and the error string as the only deltas. A single composite action (or a matrixed manifest job keyed on agent/image) would keep the invariant list from drifting per agent.

Also applies to: 731-791, 915-975

🤖 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/base-image.yaml around lines 549 - 609, Consolidate the
duplicated contract generation and validation blocks used by the Hermes, Deep
Agents Code, and OpenClaw sections into one reusable composite action or
matrix-driven manifest flow. Parameterize the agent, image, and related output
values, while preserving the shared contract schema and jq invariants exactly;
remove the three independently maintained copies.

---

536-547: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick win

Use --format for imagetools inspect digests Replace the sed scrape of the Digest: line with docker buildx imagetools inspect --format '{{.Manifest.Digest}}' in the three base-image.yaml publish blocks and the managed-images.yaml cohort-alias block; keep the existing cmp check.

🤖 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/base-image.yaml around lines 536 - 547, Replace the
sed-based Digest scraping in the publish block at
.github/workflows/base-image.yaml lines 536-547 and the cohort-alias block at
.github/workflows/managed-images.yaml lines 738-747 with docker buildx
imagetools inspect --format '{{.Manifest.Digest}}'. Preserve the existing
single-digest validation, reference construction, and cmp check; apply the same
format-based digest retrieval to all three base-image.yaml publish blocks.

test/e2e/support/base-image-publication.test.ts (1)

267-288: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Asserting the full git argv locks in incidental flag ordering.

The behaviors that matter are the :(glob) pathspec magic and first-parent scoping; --format=/--name-only order is incidental and will break this test on any harmless refactor. Consider asserting the invariants instead (each call contains --first-parent, ends with the expected :(glob) pathspec, and targets EXPECTED_SHA).

As per path instructions, "Prefer observable outcomes through the public boundary over source-text, private-shape, or mock-call assertions."

🤖 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 `@test/e2e/support/base-image-publication.test.ts` around lines 267 - 288,
Update the assertions around the git calls in the base-image publication test to
verify observable invariants rather than the complete argv ordering: each call
must include --first-parent, target EXPECTED_SHA, and end with the expected
:(glob) pathspec for agents or src/lib/messaging. Remove dependence on
incidental --format=/--name-only ordering while preserving validation of both
expected pathspecs.

Source: Path instructions

test/managed-image-publication-workflow.test.ts (2)

137-156: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Marker lists assert workflow source text rather than behavior.

validationMarkers and the jq-fragment substring checks pin exact shell/jq text, so any harmless rewording of the workflow scripts fails these tests even though the guarantees still hold. The runPublicationBarrier / runManagedImagePromotion tests below already prove the barrier and promotion behavior by executing the extracted scripts; consider trimming the string markers to the few that cannot be executed (e.g. provenance/sbom inputs) and leaning on the executed-script tests for the rest.

As per path instructions, "Prefer observable outcomes through the public boundary over source-text, private-shape, or mock-call assertions."

Also applies to: 183-193

🤖 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 `@test/managed-image-publication-workflow.test.ts` around lines 137 - 156, Trim
validationMarkers and forbiddenPerLanePromotionMarkers in the workflow
publication tests to only non-executable guarantees that cannot be covered
behaviorally, such as provenance or SBOM inputs. Remove redundant exact shell/jq
substring assertions for behavior already exercised by runPublicationBarrier and
runManagedImagePromotion, while preserving those executed-script tests as the
source of truth.

Source: Path instructions

---

646-650: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

displayAgent ternary has identical branches.

Both arms return agent, so the variable is dead indirection — use agent directly.

♻️ Proposed cleanup

-          const displayAgent =
-            agent === "langchain-deepagents-code" ? "langchain-deepagents-code" : agent;
           return {
-            name: `managed-image-${displayAgent}-${artifactPlatform}`,
+            name: `managed-image-${agent}-${artifactPlatform}`,

🤖 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 `@test/managed-image-publication-workflow.test.ts` around lines 646 - 650,
Remove the redundant displayAgent variable in the managed image publication
workflow test and use agent directly when constructing the name and path fields
in the returned object. Preserve the existing output values and artifact path
structure.

tools/e2e/base-image-publication.mts (1)

242-291: 🚀 Performance & Scalability | 🔵 Trivial | 🏗️ Heavy lift

Full-history glob expansion is unbounded and then splatted into a single git argv.

git log --name-only <sha> -- :(glob)agents/** enumerates every path ever touched under the glob across the whole first-parent history (not just paths present at expectedSha). For agents/**, scripts/**, and src/lib/messaging/** that can be many thousands of entries, all of which are then spread into one git log invocation at Line 323 — slow, and at risk of exceeding the argv limit as history grows.

Since git already accepts pathspec magic, the expansion is avoidable: pass :(glob)<path> for reviewed globs and literals otherwise directly to the relevant-commit query, keeping the validation you have for the returned SHA. If you keep expansion for evidence purposes, bound it with git ls-tree -r --name-only <sha> -- :(glob)<path> (paths at the tip) instead of full history.

🤖 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 `@tools/e2e/base-image-publication.mts` around lines 242 - 291, Update
expandBaseImagePushPaths to avoid enumerating full first-parent history for
reviewed globs. Pass each reviewed path as a Git pathspec directly to the
relevant-commit query, while retaining literal handling for non-glob paths and
the existing returned-SHA/path validation. If expansion remains necessary, use
tip-only ls-tree results for expectedSha rather than git log history.

🤖 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/base-image.yaml:
- Around line 549-609: Consolidate the duplicated contract generation and
validation blocks used by the Hermes, Deep Agents Code, and OpenClaw sections
into one reusable composite action or matrix-driven manifest flow. Parameterize
the agent, image, and related output values, while preserving the shared
contract schema and jq invariants exactly; remove the three independently
maintained copies.
- Around line 536-547: Replace the sed-based Digest scraping in the publish
block at .github/workflows/base-image.yaml lines 536-547 and the cohort-alias
block at .github/workflows/managed-images.yaml lines 738-747 with docker buildx
imagetools inspect --format '{{.Manifest.Digest}}'. Preserve the existing
single-digest validation, reference construction, and cmp check; apply the same
format-based digest retrieval to all three base-image.yaml publish blocks.

In `@test/e2e/support/base-image-publication.test.ts`:
- Around line 267-288: Update the assertions around the git calls in the
base-image publication test to verify observable invariants rather than the
complete argv ordering: each call must include --first-parent, target
EXPECTED_SHA, and end with the expected :(glob) pathspec for agents or
src/lib/messaging. Remove dependence on incidental --format=/--name-only
ordering while preserving validation of both expected pathspecs.

In `@test/managed-image-publication-workflow.test.ts`:
- Around line 137-156: Trim validationMarkers and
forbiddenPerLanePromotionMarkers in the workflow publication tests to only
non-executable guarantees that cannot be covered behaviorally, such as
provenance or SBOM inputs. Remove redundant exact shell/jq substring assertions
for behavior already exercised by runPublicationBarrier and
runManagedImagePromotion, while preserving those executed-script tests as the
source of truth.
- Around line 646-650: Remove the redundant displayAgent variable in the managed
image publication workflow test and use agent directly when constructing the
name and path fields in the returned object. Preserve the existing output values
and artifact path structure.

In `@tools/e2e/base-image-publication.mts`:
- Around line 242-291: Update expandBaseImagePushPaths to avoid enumerating full
first-parent history for reviewed globs. Pass each reviewed path as a Git
pathspec directly to the relevant-commit query, while retaining literal handling
for non-glob paths and the existing returned-SHA/path validation. If expansion
remains necessary, use tip-only ls-tree results for expectedSha rather than git
log history.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 5cc1220e-6e4c-447f-b4ec-1371c7f73a90

📥 Commits

Reviewing files that changed from the base of the PR and between 7b55b5d and 9e99181.

📒 Files selected for processing (6)

• .github/workflows/base-image.yaml
• .github/workflows/managed-images.yaml
• test/e2e/support/base-image-publication.test.ts
• test/helpers/managed-image-publication-barrier.ts
• test/managed-image-publication-workflow.test.ts
• tools/e2e/base-image-publication.mts