# Release and Deployment Page UI

**Status:** Approved target-state behavior  
**Activation:** I6.

## Page Job

Answer:

```text
What exact software is being released?
Which environments have this Release?
What is deploying now and why?
Which gates/approvals/evidence remain?
Is rollout healthy?
What is the previous safe release and rollback path?
```

## Information Architecture

The page distinguishes immutable Release contents from per-Environment Deployment history.

```text
Release header
  version/source/artifact digests/evidence

Environment promotion lane/table
  Development / Staging / Production / custom
  current Release
  latest Deployment status/health
  pending Approval/gate

Selected Deployment detail
  preflight/diff
  timeline
  rollout/health
  provider refs
  rollback/resolution
```

## Release Header

Show exact merged source, Artifact digest(s), SBOM/provenance/signature/vulnerability state, release strategy, created by/time and direct links back to ChangeSet/CI/Plan.

## Environment Promotion

Each environment row shows current deployed Release, target connection/resource, latest status/health, pending promotion and protection policy. Same artifact identity is visually clear across environments.

## Deployment Detail

Before apply: rendered target/diff summary, config provenance, required Approval/evidence. During: rollout steps/resources/health with provider links. Failure: classified reason, current safe state, deterministic/resolver activity and recommended rollback/forward-fix.

## Primary Action

State-specific and risk-proportional:

- Promote to staging;
- Approve production;
- Deploy;
- Retry safe operation;
- Roll back to Release X;
- View/resolve incident.

Confirmation states identify exact Release/Environment/impact. No vague `Deploy now` against mutable state.

## States

Release candidate/not ready, ready, promotion waiting, active Deployment, health verifying, succeeded, failed, rollback in progress/failed, provider degraded, Release quarantined/withdrawn.

## Responsive / Accessibility

Environment lanes become ordered rows/cards on small screens; do not use horizontal kanban that obscures exact versions. Diff/preflight/detail open as drawer/drill-in. Status and evidence accessible by text.

## URL Truth

Stable Release route; selected Environment/Deployment as stable subroute/query. Historical Deployments read-only with clear rollback ancestry.

## Increment Realization

I2 specifies strategy; I5 supplies verification; I6 activates page; I8 incident/resolver integration; I9 reliability/enterprise policy may add indicators without replacing page model.

## High-Fidelity Requirements

Before I6: Release ready/promotion, active rollout, failed+rollback choice, successful multi-environment history, production Approval confirmation and narrow-screen state.

## Target State

Release/Deployment is the trusted promotion surface from immutable build/release identity into environment-specific deployment history. It makes exact artifact provenance, protection gates, rollout health and recovery explicit while keeping mechanical Kubernetes/provider reconciliation replaceable.

## Primary Users / Jobs

- release owner/delivery lead: know exactly what is eligible for promotion and where it is deployed;
- authorized operator: perform staging/production promotion or rollback safely;
- engineer/resolver: diagnose a failed rollout and choose deterministic recovery, forward-fix or rollback.

## Entry / Exit Points

Entry: Project Delivery, Release/Deployment collections, CI/Merge completion, Attention approval, Incident, search. Exit: source Plan/ChangeSet/CI, Artifact/provenance evidence, Environment/Connection, Approval, Incident/Resolver, or provider-native rollout detail for secondary debugging.

## User Journeys

### J1 — Promote an immutable Release

```text
Release ready
 -> confirm source/artifact digest/provenance/evidence
 -> select target Environment
 -> inspect preflight/diff + protection policy
 -> Approve/Deploy as required
 -> durable Deployment starts
 -> rollout/health verifies
 -> Environment shows exact Release
```

### J2 — Production approval

```text
production promotion waiting
 -> Attention/Deployment detail
 -> exact Release + Environment + consequence
 -> policy/Approval revalidation
 -> approve once
 -> Deployment starts or remains blocked with explicit reason
```

### J3 — Recover failed rollout

```text
Deployment failure
 -> preserve current safe state + previous-known-good Release
 -> classify failure
 -> deterministic resolver/retry if safe
 -> otherwise Incident/agentic resolver or explicit rollback
 -> health verification
 -> resolution + history preserved
```

### J4 — Audit environment history

```text
open Environment/Release history
 -> inspect current Release and previous Deployments
 -> trace source -> Artifact -> Release -> Deployment
 -> inspect rollback ancestry/evidence
 -> historical entries remain read-only
```

## Data / Source of Truth

Artifact digest/provenance, immutable Release, Environment and Deployment records are AWP truth. Helm render/SSA/Kubernetes rollout IDs are provider mechanics/mappings. Health/telemetry is evidence used by Deployment state/policy; it does not rewrite release identity.

## Actions / Authorization

Promotion/deploy/rollback obey Environment protection, capability and Approval policy. Production/destructive actions require live authoritative checks. A provider credential or kubectl access does not itself authorize an AWP Deployment. Historical Deployments are read-only.

## Async / Duplicate-Mutation Safety

Promote/deploy/rollback uses exact Release/Environment/config revisions and idempotency protection, acknowledges immediately and returns durable Deployment identity. Duplicate submit cannot create competing rollouts. If preflight/policy/config changes, stale command is rejected for review rather than applied to new state.

## Invariants From Day 1

- Release contents are immutable;
- Environment deployment state is separate from Release identity;
- same artifact digest is promoted when policy requires artifact immutability;
- production actions never execute from stale/offline UI state;
- rollback identifies exact prior Release and resulting Deployment;
- provider rollout state is mapped into, not substituted for, AWP Deployment history.

## Current Implementation State

Target page only. No Release/Deployment product UI is active before I6.

## Deferred Realization

I8 adds generic Incident/Resolver integration; I9 reliability/tenant/governance indicators. Flux/Flagger remain trigger-only providers, not baseline page semantics.

## Temporary Dogfood Behavior

Before I6, I1 ends at trusted Merge. If AWP itself needs manual deployment during early dogfood, that operational procedure does not create a temporary competing Release/Deployment product model.

## Related Contracts / Decisions

- [`../domains/artifacts-provenance.md`](../domains/artifacts-provenance.md)
- [`../domains/releases.md`](../domains/releases.md)
- [`../domains/environments.md`](../domains/environments.md)
- [`../domains/deployments.md`](../domains/deployments.md)
- [`../workflows/merge-to-production.md`](../workflows/merge-to-production.md)
- [`../workflows/deployment-resolution.md`](../workflows/deployment-resolution.md)
- [`approval.md`](approval.md), [`incident.md`](incident.md), [`ci.md`](ci.md)

## Decisions / ADRs

Helm render + Kubernetes Server-Side Apply is the baseline provider mechanic. Flux/Flagger adoption requires their documented trigger/Decision and cannot alter AWP Release/Deployment identity.

## Visual Mockup Authority

No I6 high-fi is approved yet. Release ready/promotion, active rollout, failure/recovery/rollback, successful environment history, production Approval and narrow states require explicit approval before implementation.

## Acceptance

User can prove exactly what is in each environment and why a deployment may proceed or is blocked, with a safe recovery action visible when rollout fails.