Runbook: Release Orchestrator Required Evidence Is Missing

Audience: Platform and Security on-call engineers.

Current implementation

Verified against src/ReleaseOrchestrator on 2026-07-31. The old Promotion/Gate/Security/SecurityGate and its SEC_* violation vocabulary were unregistered dark code and have been removed. Do not diagnose a current release from those deleted types or configuration flags.

The live promotion decision is composed through the WebApi gate-plugin registry:

• sbom-readiness waits while Scanner has no ready SBOM for a component digest and denies when Scanner reports failure;
• attestation-gate verifies the configured scan/SBOM attestation contract;
• reachability-gate evaluates reachability evidence;
• approval-policy applies the operator-managed approval policy and the Policy Engine verdict.

The live sources are under src/ReleaseOrchestrator/__Apps/StellaOps.ReleaseOrchestrator.WebApi/GatePlugins/ and are composed by PluginBackedGateDecisionEvaluator.

Diagnose

1. Run the implemented promotion-gate health check:

   stella doctor --check check.release.promotion.gates
   

2. Read the persisted gate trace for the approval:

   curl -s "$ORCH_URL/api/v1/approvals/<approval-id>/gates" \
     -H "Authorization: Bearer $TOKEN" \
     -H "X-Tenant-Id: $TENANT"
   

   The endpoint requires release:read. Use the returned gate type, status, message, and details as the diagnosis; do not infer a deleted SEC_* code.

3. Inspect the durable evidence reference set and registered release evidence:

   curl -s "$ORCH_URL/api/v1/approvals/<approval-id>/evidence" \
     -H "Authorization: Bearer $TOKEN" \
     -H "X-Tenant-Id: $TENANT"
   
   curl -s "$ORCH_URL/api/release-orchestrator/evidence?releaseId=<release-id>" \
     -H "Authorization: Bearer $TOKEN" \
     -H "X-Tenant-Id: $TENANT"
   

4. For sbom-readiness, match the message to the live states:

   • waiting on SBOM results means the component digest is absent, pending, or still scanning;
   • SBOM scan failed is a deny and includes Scanner’s failure detail when available;
   • when external attachment is required, waiting on external registry attachment waits and SBOM generated but registry attachment failed denies.

Resolve and verify

• Produce the missing evidence in its owning service for the exact immutable component digest. Release Orchestrator consumes evidence; it does not invent or regenerate Scanner, attestation, or reachability results.
• For SBOM readiness, run the supported Scanner flow for that digest and correct any reported scan or external-attachment failure.
• For attestation or reachability failures, follow the gate’s returned message and the owning module’s runbook. Do not weaken the gate to mask an unavailable dependency.
• Re-read /api/v1/approvals/<approval-id>/gates and rerun the Doctor check. A resolution is complete only when the live gate trace reports the expected non-blocking result.

Related resources

• docs/modules/release-orchestrator/workflow/evidence-based-release-gates.md
• docs/modules/release-orchestrator/gates/reachability-gate.md
• docs/operations/runbooks/orchestrator-gate-timeout.md
• docs/modules/evidence-locker/promotion-evidence-contract.md