Skip to content

refactor: bootstrap the canonical Remote Dev image package - #59

Merged
eXPerience83 merged 18 commits into
mainfrom
refactor/canonical-image-naming
Aug 1, 2026
Merged

refactor: bootstrap the canonical Remote Dev image package#59
eXPerience83 merged 18 commits into
mainfrom
refactor/canonical-image-naming

Conversation

@eXPerience83

Copy link
Copy Markdown
Owner

What changed

  • defines canonical local image names remote-dev-base:local and remote-dev:local;
  • adds bounded REMOTE_DEV_BASE_IMAGE / REMOTE_DEV_IMAGE resolution with BASE_IMAGE / CODEX_IMAGE compatibility through v0.1.x;
  • makes canonical variables take precedence and reports conflicting legacy values;
  • tags the canonical local images with codex-remote-dev-base:local and codex-remote-dev:local compatibility aliases and verifies identical image IDs;
  • labels the final OCI image as Remote Dev while retaining the legacy documentation symlink;
  • builds and scans one canonical GHCR candidate under ghcr.io/experience83/remote-dev;
  • promotes that exact scanned digest to both canonical and legacy edge/stable tags;
  • verifies canonical and compatibility package tags resolve to the scanned digest;
  • publishes reviewed PR candidates only under the canonical package;
  • updates the release contract and changelog.

Safe two-step migration

GitHub creates a newly published GHCR package as private. This PR deliberately keeps the checked-in Compose and README defaults on the existing public codex-remote-dev package.

After merge and the first successful edge publication:

  1. make the new remote-dev package Public in GitHub package settings;
  2. verify an anonymous pull and that canonical/legacy tags share the digest;
  3. use a separate PR to switch Compose and documentation to REMOTE_DEV_IMAGE and the canonical package.

No anonymous deployment is pointed at a private package.

Compatibility

  • codex-remote-dev is not rebuilt separately; it is another name for the same promoted digest;
  • CODEX_IMAGE and the legacy public package remain supported throughout v0.1.x and will not be removed before v0.2.0;
  • local legacy tags point to the same image IDs as canonical local tags;
  • the shared public base package remains remote-dev-base.

Deliberately out of scope

No Compose default switch, launcher/gateway, new services, mounts, data-root migration, Antigravity, Claude Code or Context7 changes.

Validation

  • canonical/legacy variable resolution tests;
  • Bash and workflow syntax/configuration checks;
  • local image ID alias equality;
  • existing runtime and Codex smoke tests;
  • bundled notices;
  • canonical SBOM and Trivy scans;
  • no-fixable-critical gate;
  • edge/stable workflow checks that both package names resolve to the one scanned digest.

Part of #25. The follow-up deployment-default PR is intentionally blocked on public visibility of the first canonical GHCR package.

@coderabbitai

coderabbitai Bot commented Aug 1, 2026

Copy link
Copy Markdown

Review Change Stack

Warning

Review limit reached

@eXPerience83, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 46 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 87792e32-aa36-4e29-ba37-80b6f4a04b08

📥 Commits

Reviewing files that changed from the base of the PR and between dc1a8dc and 886d49a.

📒 Files selected for processing (6)
  • .github/workflows/publish-amd64.yml
  • .github/workflows/publish-edge-amd64.yml
  • CHANGELOG.md
  • Makefile
  • docs/releases.md
  • scripts/test-image-name-compat.sh

Summary by CodeRabbit

  • New Features

    • Introduced canonical remote-dev and remote-dev-base image names for local builds, CI, and published packages.
    • Continued support for legacy image names through compatibility aliases and migration warnings.
    • Added validation that canonical and legacy tags reference identical images.
  • Bug Fixes

    • Improved release verification by scanning exact image digests and confirming promoted tags resolve correctly.
  • Documentation

    • Updated release, security, and rollback guidance for the new naming and transition process.
  • Chores

    • Renamed the local starter package archive to remote-dev-containers-starter.tar.gz.

Walkthrough

The PR standardizes image naming on remote-dev and remote-dev-base. It adds compatibility resolution and tests, updates local and CI builds, preserves legacy aliases, verifies digest parity, and updates release documentation.

Changes

Remote Dev image naming and publication

Layer / File(s) Summary
Image-name compatibility contract
scripts/lib/remote-dev-image-names.sh, scripts/test-image-name-compat.sh
Adds canonical and legacy image-name resolution, alias tagging, warnings, and coverage for precedence, defaults, fallbacks, and conflicts.
Local image build and validation
images/codex/Dockerfile, scripts/build-local.sh, Makefile
Uses canonical image tags for builds and smoke tests, creates legacy aliases, compares image IDs, expands shell validation, and renames the starter archive.
AMD64 build workflow alignment
.github/workflows/build-amd64.yml
Validates aliases and uses canonical Remote Dev names for notices, SBOMs, vulnerability scans, gates, and artifacts.
Candidate and release publication
.github/workflows/publish-pr-candidate-amd64.yml, .github/workflows/publish-amd64.yml, .github/workflows/publish-edge-amd64.yml
Builds and scans canonical images, publishes canonical tags, retains required legacy tags, and verifies promoted tags against scanned digests.
Release and migration guidance
CHANGELOG.md, docs/releases.md
Documents canonical packages, compatibility tags, digest verification, visibility setup, stable publication parity, and rollback references.

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

Sequence Diagram(s)

sequenceDiagram
  participant BuildWorkflow
  participant ImageRegistry
  participant Trivy
  participant PromotionVerifier
  BuildWorkflow->>ImageRegistry: Build and push remote-dev candidate
  BuildWorkflow->>Trivy: Scan candidate digest
  Trivy-->>BuildWorkflow: Vulnerability report
  BuildWorkflow->>ImageRegistry: Promote canonical and legacy tags
  BuildWorkflow->>PromotionVerifier: Verify tag digest parity
  PromotionVerifier-->>BuildWorkflow: Promotion validation result
Loading

Possibly related PRs

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly summarizes the primary change: bootstrapping the canonical Remote Dev image package.
Description check ✅ Passed The description covers the changes, migration impact, compatibility, validation, release safety, scope, and follow-up requirements.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.
✨ 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 refactor/canonical-image-naming

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

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

Copy link
Copy Markdown
Owner Author

@codex review

Please review the current head dc1a8dc749cda273f2c24b73f06ce485a1b84923. Focus on the bounded canonical-image bootstrap: canonical/legacy variable precedence, same-ID local aliases, and edge/stable promotion of exactly one scanned digest to both GHCR package names. Do not broaden this into the Compose default switch, launcher, services, mounts or state migration.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 3

🤖 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 @.github/workflows/publish-amd64.yml:
- Around line 224-235: Validate every runtime tag emitted by promotion: in
.github/workflows/publish-amd64.yml lines 224-235, check versioned, stable,
stable-amd64, and latest tags for both runtime packages; in
.github/workflows/publish-edge-amd64.yml lines 225-236, check edge, edge-amd64,
and sha-${GITHUB_SHA} tags for both packages, comparing each tag_ref digest with
the scanned digest. Update docs/releases.md lines 21-23 to state only the exact
scope proven by these validations.

In `@CHANGELOG.md`:
- Around line 32-33: Update the changelog’s digest-parity statement to apply
only to edge and stable publication, or explicitly document that candidate-pr
releases do not publish a matching codex-remote-dev candidate package. Keep the
documented canonical GHCR package and compatibility relationship aligned with
the implemented workflow behavior.

In `@scripts/test-image-name-compat.sh`:
- Around line 60-62: Replace the bare warning-content grep after the conflicting
canonical-value assertion with an explicit failure check that emits an ERROR
message when the expected override text is absent. Keep the existing
fixed-string pattern and warning_file validation, matching the descriptive
failure behavior used by assert_eq and other checks in the script.
🪄 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: ASSERTIVE

Plan: Pro Plus

Run ID: e551ced1-24fc-4014-9013-ade29d20fd10

📥 Commits

Reviewing files that changed from the base of the PR and between fdf3232 and dc1a8dc.

📒 Files selected for processing (11)
  • .github/workflows/build-amd64.yml
  • .github/workflows/publish-amd64.yml
  • .github/workflows/publish-edge-amd64.yml
  • .github/workflows/publish-pr-candidate-amd64.yml
  • CHANGELOG.md
  • Makefile
  • docs/releases.md
  • images/codex/Dockerfile
  • scripts/build-local.sh
  • scripts/lib/remote-dev-image-names.sh
  • scripts/test-image-name-compat.sh
📜 Review details
⏰ Context from checks skipped due to timeout. (1)
  • GitHub Check: build
🧰 Additional context used
📓 Path-based instructions (4)
images/**/Dockerfile

⚙️ CodeRabbit configuration file

images/**/Dockerfile: Review for reproducibility, supply-chain security and minimal image growth.
Require pinned upstream versions and checksum or digest verification for downloaded binaries.
Flag secrets, floating base tags, unsafe remote-script execution, broken multi-architecture logic,
cache misuse, unnecessary packages and changes that weaken the secure-by-default runtime.

Files:

  • images/codex/Dockerfile
.github/workflows/**

⚙️ CodeRabbit configuration file

.github/workflows/**: Review GitHub Actions for least-privilege permissions, safe event triggers, untrusted input handling,
accidental publication, tag-channel correctness, secret exposure, reproducible builds, SBOM/provenance
generation and appropriate validation before pushing images.

Files:

  • .github/workflows/publish-pr-candidate-amd64.yml
  • .github/workflows/build-amd64.yml
  • .github/workflows/publish-edge-amd64.yml
  • .github/workflows/publish-amd64.yml
scripts/**/*.sh

⚙️ CodeRabbit configuration file

scripts/**/*.sh: Review as production Bash. Check quoting, set -euo pipefail behavior, cleanup traps,
bounded retries and timeouts, non-interactive execution, idempotency and useful failure messages.
Flag commands that can hang, leak credentials, silently ignore failures or mutate persistent data unexpectedly.

Files:

  • scripts/lib/remote-dev-image-names.sh
  • scripts/build-local.sh
  • scripts/test-image-name-compat.sh
**/*.md

⚙️ CodeRabbit configuration file

**/*.md: Check that documentation matches the implemented behavior and clearly distinguishes experimental edge builds
from stable releases. Flag outdated versions, unsafe deployment guidance and claims not proven by CI or testing.

Files:

  • CHANGELOG.md
  • docs/releases.md
🪛 Shellcheck (0.11.0)
scripts/test-image-name-compat.sh

[info] 26-26: Expressions don't expand in single quotes, use double quotes for that.

(SC2016)

🔇 Additional comments (14)
.github/workflows/build-amd64.yml (4)

50-51: LGTM!


64-93: LGTM!


124-128: 🗄️ Data Integrity & Integration

No action needed.

No repository consumers request the previous Codex report filenames by exact path.


95-104: 🔒 Security & Privacy

No change needed for the Trivy gate.

scripts/enforce-trivy-gate.sh rejects missing, empty, or malformed JSON reports and fails on fixable CRITICAL findings before the workflow can complete.

scripts/lib/remote-dev-image-names.sh (2)

8-32: LGTM!


34-44: LGTM!

scripts/test-image-name-compat.sh (2)

1-28: LGTM!


30-53: LGTM!

images/codex/Dockerfile (2)

2-2: LGTM!


12-13: LGTM!

scripts/build-local.sh (3)

7-12: LGTM!


34-41: LGTM!


72-119: LGTM!

Makefile (1)

9-20: LGTM!

Comment thread .github/workflows/publish-amd64.yml Outdated
Comment thread CHANGELOG.md Outdated
Comment thread scripts/test-image-name-compat.sh

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: dc1a8dc749

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread Makefile Outdated
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant