git.stella-ops.org/docs/modules/release-orchestrator/appendices/promotion-capsule-optional.md

Optional Promotion Capsule and human_decision Envelope

Status

Optional profile. This appendix must not block baseline promotion delivery.

Promotion Capsule (Optional)

The optional promotion capsule is a DSSE-wrapped bundle containing:

• Promotion identity (promotionId, source/target environment, artifact digests)
• Policy inputs (policy digest/version, gate input digest)
• Evidence references (evidence bundle id, attestation digests, Rekor refs)
• Decision output (allow/deny/pending + reason codes)
• Signatures and verification metadata

Suggested Envelope Type

• Media type: application/vnd.stellaops.promotion-capsule+json
• Predicate type: stella.ops/promotionCapsule@v1

Optional human_decision DSSE Envelope

For exception paths, the optional envelope captures accountable human override decisions and links them to the promotion record.

Required fields:

• decisionId (stable id)
• promotionId
• requestId (Policy exception approval request id)
• actorId
• decision (approve|reject|cancel)
• reason
• ticket
• expiresAtUtc (if temporary override)
• recordedAtUtc

Binding to Existing Approval Workflows

• Policy exception workflow APIs remain source of truth for request lifecycle.
• Optional DSSE human_decision envelope references Policy request/audit ids.
• Promotion decision records may include humanDecisionEnvelopeId when present.

SLA and Governance Notes

• human_decision should be time-bounded and non-default.
• Override paths should require explicit scope and reason metadata.
• Expired override envelopes must not authorize future promotions.

Related References

• src/Policy/StellaOps.Policy.Gateway/Endpoints/ExceptionApprovalEndpoints.cs
• src/Policy/StellaOps.Policy.Gateway/Services/ApprovalWorkflowService.cs
• docs/product/decision-capsules.md
• docs/modules/release-jobengine/workflow/promotion.md