docs(adr): ADR-013 automated attested marketplace release on catalog admission - #57
Merged
Merged
Conversation
…admission Extends ADR-010's pipeline past the admission-verified merge: a reusable auto-tag workflow, called by each marketplace on catalog-path pushes to main, computes the next patch version and pushes the tag with a release-App token, firing the existing tag-gated attested release unchanged. Amends ADR-010 (dated audit entry: extension + credential-name drift per ADR-011), adds bidirectional related links in ADR-005/ADR-011, and brings the index current (missing ADR-012 row + ADR-013).
Fifteen findings from the local review pass: dispatch bumps no longer skip on an already-tagged head (the minor/major escape hatch works); burst coalescing under the concurrency group is stated at spec level and Driver 1 reworded to freshness semantics; the dead catalog-path input is dropped and the reusable renamed catalog-agnostic (reusable-release-tag); citation corrections (hub terminal step L131-L138; ADR-010 audit-row wording); cross-reference tense fixed to accepted-pending; ADR-010's Owner-setup block annotated as superseded; stale modeled-information-format-ci references in catalog-update/README.md and the hub header corrected (line-count preserving); updated: bumped on ADR-005/011 and their related-ADR lists reconciled; audit pending rows now cover all seven work items.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR documents (via a new ADR and related amendments) the decision to automatically convert an admitted marketplace catalog change into an attested marketplace release by introducing an auto-tag “trigger seam,” and it updates existing ADR cross-links, the ADR index, and two stale identity references to align with ADR-011’s App fleet.
Changes:
- Adds ADR-013 defining an automated, attested marketplace release path after catalog admission (auto-tag seam + rollout checklist).
- Updates ADR-005/ADR-010/ADR-011 to relate to ADR-013 and records a 2026-07-05 audit note about credential-name drift.
- Updates the ADR index and corrects stale identity references in catalog opt-in docs and the hub workflow header comment.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| docs/adr/README.md | Adds missing ADR-012 index row and new ADR-013 index row. |
| docs/adr/ADR-013-marketplace-release-automation.md | New ADR defining the auto-tag seam that triggers existing tag-gated attested releases post-admission. |
| docs/adr/ADR-011-least-privilege-app-fleet.md | Updates updated: and adds ADR-013 as related/context in the App-fleet ADR. |
| docs/adr/ADR-010-plugin-catalog-hub.md | Updates updated:, adds ADR-013 relation, and documents/audits credential-name drift context. |
| docs/adr/ADR-005-signing-attestation-verification.md | Updates updated: and adds ADR-013 relation explaining release triggering remains tag-gated. |
| catalog-update/README.md | Updates opt-in identity reference from the retired App name to the org catalog App. |
| .github/workflows/plugin-catalog-update-hub.yml | Updates header comment to reference the org catalog App instead of the retired App name. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
The opt-in text named two of the three permissions auth/apps.json grants the catalog App; actions: write was missing.
ADR-005 gains a Negative consequence: a verified attestation proves the configured scanners (SAST/SCA/secrets/container/IaC/DAST/VEX) found no qualifying issue, not that the artifact is free of vulnerabilities outside their coverage. ADR-013 gains a matching Negative consequence and a Decision Outcome note: automating the release tag removes the last human checkpoint on a release without replacing it with anything stronger than the gate suite already provided; widening that coverage is a separate decision, out of scope here.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR records the decision that closes the gap between catalog admission and marketplace release: an admitted catalog change now has a defined, automated path to an attested marketplace release. It adds one new Architecture Decision Record (ADR), amends three others, brings the ADR index current and corrects two stale identity references found during the work.
What changed
docs/adr/ADR-013-marketplace-release-automation.md). Decides how an admitted plugin-catalog change becomes an attested marketplace release. Includes a seven-item implementation checklist and a pending-row audit so build work can start directly from the ADR.CATALOG_UPDATER_APP_*toCATALOG_CLIENT_APP_*credential drift (the rename belongs to ADR-011). The historical Owner-setup block is annotated as superseded so nobody re-runs retired provisioning commands.updated:bumped.main(ADR-012 landed in docs: OSV-Scanner rollout ADR, reference, and runbook #43 without an index update).catalog-update/README.mdand the hub workflow's header comment still named the retiredmodeled-information-format-ciApp; both now name thecatalogApp per ADR-011. Both edits preserve line counts, so existingfile:linecitations in the ADRs remain valid.Why
The catalog pipeline recorded in ADR-010 ends at the admission-verified merge: the hub re-pins
marketplace.jsonverify-first,catalog-admissionre-verifies fail-closed and the PR auto-merges. Nothing follows. The marketplace's own attested release (release.yml) fires only on a manually pushedv*.*.*tag. After every admitted catalog change, the released, cosign-signed catalog therefore diverges frommainuntil someone remembers to tag. Consumers who verify the released catalog (the correct behavior) receive the stale one.The decision (ADR-013)
A compose-only trigger seam, not a pipeline change:
reusable-release-tag.yml, in this repo: a generic next-semver auto-tag seam. It computes the next patch version from the latestv*.*.*tag and pushes the annotated tag with arelease-App token. The App token is load-bearing: refs pushed with the run's ownGITHUB_TOKENdo not trigger workflows.push: main, path-filtered to.claude-plugin/marketplace.json. The tag then fires the existing tag-gated attested release pipeline unchanged.workflow_dispatchbumpinput that does not skip on an already-tagged head. Push-triggered runs skip when the head commit is already tagged, so manual tags win.Validation
smadrmode (0 errors) and MIF conformance at levels 1, 2 and 3. The index README validates at MIF level 1. ADR-011 and ADR-012 still pass.maintoday; this PR does not touch them.