ADR-0003: Adopt the Attested-Delivery Release Pattern
ADR-0003: Adopt the Attested-Delivery Release Pattern
Section titled “ADR-0003: Adopt the Attested-Delivery Release Pattern”Status
Section titled “Status”Accepted
Context
Section titled “Context”Background and Problem Statement
Section titled “Background and Problem Statement”The mif-docs plugin is publicly installable from the org marketplace: anyone
can claude plugin install mif-docs@modeled-information-format and run its
scripts and hooks. A publicly installed artifact is a supply-chain surface — an
installer needs to know the bytes they run were built from this repo’s source by
this repo’s workflow, and they need to be able to check that themselves. We had
to decide how releases are produced and verified before publishing v0.1.0.
Current Limitations
Section titled “Current Limitations”- No provenance: a plain release tarball carries no evidence of how or from what it was built.
- No independent verification: without an attestation, an installer cannot confirm the artifact’s origin from their own workstation.
- Unpinned actions: floating action tags let a release’s build steps change underneath the workflow without review.
Decision Drivers
Section titled “Decision Drivers”Primary Decision Drivers
Section titled “Primary Decision Drivers”The following factors are weighted most heavily in this decision:
- Supply-chain integrity: the release shall carry build provenance binding the artifact to this repo’s source and workflow.
- Independent verifiability: an installer shall be able to verify the release attestation from a workstation, without trusting the publisher.
- Fail-closed publication: the release workflow shall verify its own attestation before upload and abort if verification fails.
Secondary Decision Drivers
Section titled “Secondary Decision Drivers”The following factors influenced the decision but were not individually decisive:
- Reproducible artifact: the tarball should be byte-reproducible from a git ref so two builds of the same ref match.
- Pinned build steps: every action should be SHA-pinned and enforced centrally, so the build cannot shift without review.
Considered Options
Section titled “Considered Options”Option 1: Plain GitHub release, no provenance
Section titled “Option 1: Plain GitHub release, no provenance”Description: Attach a tarball to a GitHub release with no attestation and no pinning enforcement.
Technical Characteristics:
- A release asset with no provenance metadata.
- Build steps may use floating action tags.
Advantages:
- Simplest possible release flow.
- No attestation tooling to wire.
Disadvantages:
- No evidence of origin; installers cannot verify the artifact.
- Floating tags let build steps change without review.
Disqualifying Factor: no provenance and no verification fail the supply-chain-integrity and independent-verifiability drivers outright.
Risk Assessment:
- Technical Risk: Low to build, High to trust.
- Schedule Risk: Low.
- Ecosystem Risk: High. A public artifact with no verifiable origin.
Option 2: Sign with an externally managed key
Section titled “Option 2: Sign with an externally managed key”Description: Produce the tarball and sign it with a long-lived signing key held in external key management.
Technical Characteristics:
- A detached signature over the artifact.
- Verification needs the publisher’s public key distributed out of band.
Advantages:
- Artifacts carry a cryptographic signature.
Disadvantages:
- A long-lived key is an operational burden and a theft target.
- No build provenance; a signature proves who signed, not how it was built.
Risk Assessment:
- Technical Risk: Medium. Key custody and rotation.
- Schedule Risk: Medium. Key management to stand up.
- Ecosystem Risk: Medium. Out-of-band key distribution and trust.
Option 3: Self-contained attested-delivery pattern
Section titled “Option 3: Self-contained attested-delivery pattern”Description: Adopt the attested-delivery pattern modeled on
research-harness-template: build a reproducible git archive tarball, attest
SLSA build provenance with actions/attest-build-provenance, then fail-closed
verify with gh attestation verify --signer-workflow before upload, with all
actions SHA-pinned and a central pin-check.
Technical Characteristics:
- Reproducible
git archivetarball bound to a tag. - SLSA build provenance via
actions/attest-build-provenance. gh attestation verify --signer-workflowgate before upload; keyless via OIDC.
Advantages:
- Every release is independently verifiable from a workstation.
- No long-lived key; identity is the run’s ephemeral OIDC workflow identity.
Disadvantages:
- More workflow surface than a plain release; mitigated by reusing a proven pattern.
Risk Assessment:
- Technical Risk: Low. A proven pattern reused as-is.
- Schedule Risk: Low. Modeled on
research-harness-template. - Ecosystem Risk: Low. Keyless, standards-based, verifiable by anyone.
Decision
Section titled “Decision”We adopt the self-contained attested-delivery pattern, modeled on
research-harness-template. The release workflow:
- Builds a reproducible
git archivetarball (mif-docs-plugin-v0.1.0.tar.gz). - Generates SLSA build provenance with
actions/attest-build-provenance. - Fail-closed verifies the attestation with
gh attestation verify --signer-workflowbefore upload, aborting on any failure. - Uploads only on a published release;
workflow_dispatchis a dry run.
All actions are SHA-pinned and enforced by a central pin-check. v0.1.0 is
released and attested.
Consequences
Section titled “Consequences”Positive
Section titled “Positive”- Workstation-verifiable releases: anyone can run
gh attestation verifyagainst a release artifact, satisfying the independent-verifiability driver. - No long-lived key: keyless OIDC signing removes a standing secret and its custody burden.
Negative
Section titled “Negative”- More workflow surface: the release pipeline is larger than a plain upload;
mitigated by reusing the proven
research-harness-templatepattern and the centralpin-check. - Verification dependency: publication depends on the verify step passing; this is intentional — fail-closed means a failed verify blocks the release.
Neutral
Section titled “Neutral”- Dry-run path:
workflow_dispatchruns the pipeline without uploading — a deliberate rehearsal mode, not a second release path.
Decision Outcome
Section titled “Decision Outcome”The decision achieves its primary objective — a publicly installable plugin whose
every release is verifiable and fail-closed — measured by: v0.1.0 released with a
verified attestation, and the marketplace catalog-admission verifying that
attestation fail-closed before listing the release.
Mitigations:
- The pattern is reused from
research-harness-templaterather than invented. pin-checkcentrally enforces SHA-pinning of every action in the pipeline.
Related Decisions
Section titled “Related Decisions”- ADR-0001: Align the adr Genre Fully to Structured MADR - the genre whose conformant output this pipeline ships.
- ADR-0002: Host Ontologies in a Separate Repository - the ontology vendored into the attested artifact.
- Runbook: Cut an Attested Release - the operational procedure that executes this pattern.
- SLSA build provenance — actions/attest-build-provenance - the action that generates the provenance this pattern verifies.
More Information
Section titled “More Information”- Date: 2026-06-30
- Source: mif-docs v0.1.0 release-architecture review
- Related ADRs: ADR-0001, ADR-0002
2026-06-30
Section titled “2026-06-30”Status: Compliant
Findings:
| Finding | Files | Lines | Assessment |
|---|---|---|---|
| Fail-closed verify-before-upload gate in place | - | - | accepted |
Summary: Decision accepted after the v0.1.0 release-architecture review; releases use the attested-delivery pattern with a fail-closed verify gate.
Action Required: Keep pin-check green and the gh attestation verify
gate fail-closed before every upload.