Add Protected Semantic Version Releases#30
Conversation
|
Warning Review limit reached
Next review available in: 10 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the 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 configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: ⛔ Files ignored due to path filters (2)
📒 Files selected for processing (45)
📝 WalkthroughWalkthroughThis change adds a protected, manually triggered release workflow using strict Semantic Versioning. It validates required checks for the exact 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
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. Comment |
4821ba6 to
018a4c0
Compare
There was a problem hiding this comment.
Pull request overview
This PR introduces a protected, manually-dispatched release workflow that enforces strict Semantic Versioning, binds publication to the exact main commit after all required checks pass, and gates final publication behind a protected GitHub Actions environment approval.
Changes:
- Adds a two-phase
create-release.ymlworkflow to verify themaincandidate (required checks, container candidates, native assets) and then publish immutable image tags + a draft GitHub Release after environment approval. - Introduces release-governance tooling and tests (
verify_release_candidate.py,promote-release-images.sh, and compliance tests) to validate SemVer, required-check status, and idempotent image promotion. - Updates documentation to describe the new release governance and Semantic Version container tagging (including
+→_mapping for OCI tags).
Reviewed changes
Copilot reviewed 13 out of 13 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Adds a maintainer-facing pointer to the protected release workflow and SemVer rules. |
| packages/compliance/tests/test_release_governance.py | New tests for SemVer validation, required-check status parsing, and image promotion idempotency. |
| packages/compliance/tests/test_container_assets.py | Extends compliance assertions to cover the new release workflow and native-release trigger expectations. |
| docs/releases.md | New release guide documenting version rules, gating, approval, and artifact/tag behavior. |
| docs/README.md | Adds the Releases doc to the documentation index. |
| docs/container-images.md | Documents protected SemVer container tags and release gating behavior. |
| design/09-implementation-plan.md | Updates implementation status language to reflect implemented release governance and remaining assurance work. |
| design/08-development.md | Adds release-governance workflow details to the development/testing posture. |
| deploy/verify_release_candidate.py | Implements SemVer validation + required check-run / commit-status evaluation for the release gate. |
| deploy/promote-release-images.sh | Verifies/publishes digest-preserving SemVer image tags from immutable sha-<gitsha> candidates. |
| .github/workflows/native-release.yml | Ensures native assets are built/verified on PRs and main (and removes release-published upload path in favor of the protected workflow). |
| .github/workflows/create-release.yml | New protected release workflow with verification and approval-gated publication. |
| .github/release-required-checks.txt | New manifest declaring the set of required main checks used by the release gate. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (2)
deploy/promote-release-images.sh (1)
46-53: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick winAdd descriptive errors for the manifest-shape checks.
Unlike the digest-mismatch checks (lines 60, 72), a failed
jq -eassertion here aborts silently viaset -ewith no message identifying which tag/shape check failed — makes a release-pipeline failure harder to diagnose.🛠️ Proposed fix to add explicit error messages
if [[ "${media_shape}" == "single" ]]; then - jq -e ' - .mediaType == "application/vnd.docker.distribution.manifest.v2+json" - and .config.mediaType == "application/vnd.docker.container.image.v1+json" - ' <<<"${raw}" >/dev/null + if ! jq -e ' + .mediaType == "application/vnd.docker.distribution.manifest.v2+json" + and .config.mediaType == "application/vnd.docker.container.image.v1+json" + ' <<<"${raw}" >/dev/null; then + echo "candidate is not a single-platform image manifest: ${source_ref}" >&2 + exit 1 + fi else - jq -e '.manifests | length > 0' <<<"${raw}" >/dev/null + if ! jq -e '.manifests | length > 0' <<<"${raw}" >/dev/null; then + echo "candidate is not a multi-platform manifest list: ${source_ref}" >&2 + exit 1 + fi fi🤖 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 `@deploy/promote-release-images.sh` around lines 46 - 53, Update the manifest-shape checks in the media_shape conditional to handle failed jq -e assertions explicitly, emitting descriptive errors that identify the affected tag and whether the single or multi-manifest validation failed before exiting. Preserve the existing validation expressions and success behavior.packages/compliance/tests/test_release_governance.py (1)
91-154: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winTest only covers the promote happy path.
This test exercises
promotemode's create-then-idempotent-skip path, but never runsverifymode (which must exit without callingimagetools create, perpromote-release-images.shlines 55-57) and never exercises the digest-mismatch failure branches (lines 59-62, 71-74). These are the exact policy-decision branches most likely to hide a regression in a release-gating script.As per coding guidelines, "Add or update tests when changing detector logic, policy decisions, adapter behavior, skill validation, audit records, attestation export, CLI output, notebook view models, or web-UI view models" for
**/*.{py,ts,tsx}.🤖 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 `@packages/compliance/tests/test_release_governance.py` around lines 91 - 154, Add coverage alongside test_release_image_promotion_is_complete_and_idempotent for promote-release-images.sh verify mode, asserting it exits successfully without invoking imagetools create. Also add cases for each digest-mismatch failure branch in promote and verify, asserting a nonzero exit and the expected failure behavior while preserving the existing happy-path and idempotency assertions.
🤖 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/create-release.yml:
- Around line 58-85: Update the “Wait for required checks on the exact commit”
retry loop so transient failures from either gh api call are handled within the
loop instead of triggering immediate bash errexit termination. Capture each API
command’s status, log the polling failure, sleep, and retry while preserving
verify_release_candidate.py’s existing exit-code handling and the 60-attempt
timeout.
- Around line 86-91: Add a docker/login-action step before “Verify immutable
container candidates” in the release workflow, authenticating to GHCR with the
existing registry credentials and appropriate GitHub token. Keep the verify
command and its RELEASE_VERSION/GITHUB_SHA inputs unchanged.
- Around line 160-179: The release-existence handling should distinguish draft
releases from published releases so reruns can resume after the draft creation
step. Update the existing release freshness-check flow to branch on isDraft,
publishing the existing draft via the release-edit path and only failing for an
already published release; preserve the normal create-then-publish flow for new
releases.
---
Nitpick comments:
In `@deploy/promote-release-images.sh`:
- Around line 46-53: Update the manifest-shape checks in the media_shape
conditional to handle failed jq -e assertions explicitly, emitting descriptive
errors that identify the affected tag and whether the single or multi-manifest
validation failed before exiting. Preserve the existing validation expressions
and success behavior.
In `@packages/compliance/tests/test_release_governance.py`:
- Around line 91-154: Add coverage alongside
test_release_image_promotion_is_complete_and_idempotent for
promote-release-images.sh verify mode, asserting it exits successfully without
invoking imagetools create. Also add cases for each digest-mismatch failure
branch in promote and verify, asserting a nonzero exit and the expected failure
behavior while preserving the existing happy-path and idempotency assertions.
🪄 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: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: c9d4c87e-95bf-4cf4-9c72-27488ef9bc41
📒 Files selected for processing (13)
.github/release-required-checks.txt.github/workflows/create-release.yml.github/workflows/native-release.ymlREADME.mddeploy/promote-release-images.shdeploy/verify_release_candidate.pydesign/08-development.mddesign/09-implementation-plan.mddocs/README.mddocs/container-images.mddocs/releases.mdpackages/compliance/tests/test_container_assets.pypackages/compliance/tests/test_release_governance.py
1fc50fc to
73d0f42
Compare
73d0f42 to
1e50ab0
Compare
### ♻️ Current Situation & Problem Native release assets are built when a GitHub Release is published, but publication is not bound to the successful `main` checks for the exact tagged commit. A release can therefore exist before native packaging succeeds, main-only CPU and GPU image publication is not part of the gate, and no protected approval separates candidate verification from publication. ### ⚙️ Release Notes - Add a manually dispatched release workflow that accepts strict Semantic Versioning without a `v` prefix and binds publication to the current `main` commit. - Require every declared main check, verify immutable generic, Terra, generic GPU, and Terra GPU candidates, and rebuild and test native assets before approval. - Publish digest-preserving Semantic Version image tags, attest native assets, create a complete draft, and publish the Git tag and immutable GitHub Release only after approval. - Run native asset validation on every pull request and `main` commit. - Configure the `release` environment with required maintainer approval and self-review enabled, enable immutable releases, protect tags against mutation, and add native assets to the main merge ruleset. ### 📚 Documentation The release guide documents version syntax, the maintainer command, automated gates, self-approval, artifact names, image tags, build-metadata mapping, interruption behavior, and maintenance of the required-check manifest. The development, container, and delivery documents now distinguish implemented release governance from remaining signing, retention, notice, compatibility, and support work. ### ✅ Testing - 431 Python tests pass with 90.09% aggregate branch coverage. - Release tests cover valid and invalid Semantic Versions, paginated and duplicate check runs, commit-status contexts, failure and incomplete states, all four image mappings, OCI-safe build metadata, Terra flattening, and idempotent promotion. - Ruff formatting and lint, strict mypy, actionlint, shell syntax, Markdown whitespace, native installer packaging and installation smoke, and REUSE 3.3 compliance pass locally. - The verifier was exercised against the actual merged `main` commit and correctly reported still-running main-only image jobs plus the native check that this pull request adds to `main`. ### Code of Conduct & Contributing Guidelines By creating and submitting this pull request, you agree to follow our [Code of Conduct](https://github.com/SchmiedmayerLab/.github/blob/main/CODE_OF_CONDUCT.md) and [Contributing Guidelines](https://github.com/SchmiedmayerLab/.github/blob/main/CONTRIBUTING.md): - [x] I agree to follow the [Code of Conduct](https://github.com/SchmiedmayerLab/.github/blob/main/CODE_OF_CONDUCT.md) and [Contributing Guidelines](https://github.com/SchmiedmayerLab/.github/blob/main/CONTRIBUTING.md).
♻️ Current Situation & Problem
Native release assets are built when a GitHub Release is published, but publication is not bound to the successful
mainchecks for the exact tagged commit. A release can therefore exist before native packaging succeeds, main-only CPU and GPU image publication is not part of the gate, and no protected approval separates candidate verification from publication.⚙️ Release Notes
vprefix and binds publication to the currentmaincommit.maincommit.releaseenvironment with required maintainer approval and self-review enabled, enable immutable releases, protect tags against mutation, and add native assets to the main merge ruleset.📚 Documentation
The release guide documents version syntax, the maintainer command, automated gates, self-approval, artifact names, image tags, build-metadata mapping, interruption behavior, and maintenance of the required-check manifest. The development, container, and delivery documents now distinguish implemented release governance from remaining signing, retention, notice, compatibility, and support work.
✅ Testing
maincommit and correctly reported still-running main-only image jobs plus the native check that this pull request adds tomain.Code of Conduct & Contributing Guidelines
By creating and submitting this pull request, you agree to follow our Code of Conduct and Contributing Guidelines: