729 lines
44 KiB
Markdown
729 lines
44 KiB
Markdown
## Pack 12 — Release Bundle Organizer (Bundles, Bundle Versions, Component Versions, Config + Changelog per Repo)
|
||
|
||
This pack adds the missing **Release Bundle Organizer** while keeping your **release-first / digest-first** restructuring intact, and wiring it into **Release Control (regions/envs/inputs)** + **Approvals** + **Evidence** + **Operations (AirGap)**.
|
||
|
||
---
|
||
|
||
# 12.1 Menu graph (Mermaid) — where Bundle Organizer lives in the redesigned IA
|
||
|
||
> Scope: *only the parts relevant to bundles*. This keeps **Release Control** as a root menu (per your instruction) and makes **Bundles** a first-class part of **Releases**, not buried.
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
|
||
ROOT[Stella Ops Console] --> DASH[Dashboard]
|
||
ROOT --> REL[Releases]
|
||
ROOT --> APPR[Approvals]
|
||
ROOT --> SEC[Security]
|
||
ROOT --> EVID[Evidence]
|
||
ROOT --> OPS[Operations]
|
||
ROOT --> INT[Integrations]
|
||
ROOT --> RC[Release Control (ROOT)]
|
||
|
||
%% Releases submenus
|
||
REL --> REL_LIST[Releases (Promotions)]
|
||
REL --> BUNDLES[Bundles (Organizer)]
|
||
REL --> COMPONENTS[Components (Service Versions)]
|
||
|
||
%% Bundles area
|
||
BUNDLES --> B_CAT[Bundle Catalog]
|
||
BUNDLES --> B_DETAIL[Bundle Detail]
|
||
BUNDLES --> B_BUILDER[Create Bundle Version (Builder)]
|
||
BUNDLES --> BV_DETAIL[Bundle Version Detail]
|
||
BUNDLES --> B_MAT[Materialize to Environment]
|
||
BUNDLES --> B_CHANGE[Changelog (per repo)]
|
||
|
||
%% Components area
|
||
COMPONENTS --> C_CAT[Component Catalog]
|
||
COMPONENTS --> CV_DETAIL[Component Version Detail]
|
||
COMPONENTS --> C_IMPORT[Import/Sync Versions]
|
||
|
||
%% Cross-links
|
||
B_DETAIL -. "Create promotion" .-> REL_LIST
|
||
B_MAT -. "Creates approval request" .-> APPR
|
||
BV_DETAIL -. "Evidence export" .-> EVID
|
||
B_MAT -. "Uses env inputs" .-> RC
|
||
B_MAT -. "Uses Vault/Consul" .-> INT
|
||
B_MAT -. "Option: Build AirGap bundle" .-> OPS
|
||
```
|
||
|
||
---
|
||
|
||
# 12.2 Terminology (so screens stay unambiguous)
|
||
|
||
* **Component Version** = *digest-first* identity of a microservice image (digest is authoritative) + a **display version** (e.g., `2.1.0`), plus SBOM/finding snapshots and provenance links.
|
||
* **Bundle** = logical product/service-set (e.g., “Platform Release”), with many **Bundle Versions** over time.
|
||
* **Bundle Version** = immutable snapshot: exact component digests + bundle manifest digest + policy evaluation snapshot + derived changelog pointers.
|
||
* **Materialization** = resolving **environment-specific inputs** (Vault/Consul/overrides) to produce a deployment plan for a region/env (and optionally an AirGap artifact).
|
||
|
||
---
|
||
|
||
# 12.3 Screen — Bundle Catalog
|
||
|
||
### Formerly (where it “lived” pre-redesign)
|
||
|
||
* **Not a dedicated concept**. Closest proxy:
|
||
|
||
* **Releases** list (`/releases`) with “Components” count
|
||
* “AirGap Bundles” existed but under **Operations → Feeds → AirGap Bundles** (offline artifact focus, not release model focus)
|
||
|
||
### Why changed like this
|
||
|
||
* Stella is release-centric; releases should promote **bundle versions** (stable, versioned) rather than ad-hoc component lists.
|
||
* Operators need a canonical place to **organize bundles** by product/team/repo-set and track their version history.
|
||
|
||
### Screen graph (Mermaid)
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
A[Bundle Catalog] --> B[Bundle Detail]
|
||
A --> C[Create New Bundle]
|
||
A --> D[Component Catalog]
|
||
A --> E[Changelog (per repo)]
|
||
A --> F[Search/Filter by product/team/repo-set]
|
||
```
|
||
|
||
### ASCII mock
|
||
|
||
```text
|
||
┌──────────────────────────────────────────────────────────────────────────────────────────────┐
|
||
│ Releases ▸ Bundles (Organizer) │
|
||
│ Legacy: N/A (new). Previously: Releases (/releases) contained components directly. │
|
||
├──────────────────────────────────────────────────────────────────────────────────────────────┤
|
||
│ Search: [ platform ] Tags: [All] Team: [All] Repo-set: [All] Status: [Active] │
|
||
│ Actions: [+ New Bundle] [Import from Repo Set] │
|
||
├──────────────────────────────────────────────────────────────────────────────────────────────┤
|
||
│ ┌─────────────────────────────┬──────────┬───────────────┬─────────────────┬────────────────┐│
|
||
│ │ Bundle │ Versions │ Last Version │ Last Promotion │ Security Signal ││
|
||
│ ├─────────────────────────────┼──────────┼───────────────┼─────────────────┼────────────────┤│
|
||
│ │ Platform Release │ 18 │ 1.3.0-rc1 │ staging → prod │ 1 crit reachable││
|
||
│ │ Hotfix Bundle │ 6 │ 1.2.4 │ prod │ clean ││
|
||
│ │ Feature Branch Preview │ 3 │ 2.0.0-alpha │ dev │ info only ││
|
||
│ └─────────────────────────────┴──────────┴───────────────┴─────────────────┴────────────────┘│
|
||
│ Click a bundle → Bundle Detail │
|
||
└──────────────────────────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
# 12.4 Screen — Bundle Detail (Overview + Versions + Deployments)
|
||
|
||
### Formerly
|
||
|
||
* Partially in:
|
||
|
||
* **Releases** row detail (implicit)
|
||
* “Create Release” (implicit composition)
|
||
* “Approvals” (promotion context)
|
||
* But **no persistent bundle object** existed.
|
||
|
||
### Why changed like this
|
||
|
||
* Bundle is the stable unit of release governance:
|
||
|
||
* It is what you reason about (changelog, SBOM summary, reachability coverage).
|
||
* Releases become “promotions of bundle version X to env Y”.
|
||
* It’s also where you attach bundle-level intent (owner/team, repo-set, default workflow).
|
||
|
||
### Screen graph (Mermaid)
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[Bundle Detail] --> B[Versions Tab]
|
||
A --> C[Deployments/Promotions Tab]
|
||
A --> D[Components Tab]
|
||
A --> E[Config & Inputs Tab]
|
||
A --> F[Changelog Tab (per repo)]
|
||
A --> G[Create Bundle Version]
|
||
A --> H[Materialize to Environment]
|
||
```
|
||
|
||
### ASCII mock
|
||
|
||
```text
|
||
┌──────────────────────────────────────────────────────────────────────────────────────────────┐
|
||
│ Bundle: Platform Release │
|
||
│ Legacy: N/A (new). Previously: “Platform Release” existed only as a Release row in /releases │
|
||
├──────────────────────────────────────────────────────────────────────────────────────────────┤
|
||
│ Owner: ci-pipeline Team: platform Repo-set: {api-gw, user-svc, web-fe, worker} │
|
||
│ Default workflow: Canary 10→50→100 Default policy baseline: Prod │
|
||
│ │
|
||
│ Tabs: [Overview] [Versions] [Promotions] [Components] [Config & Inputs] [Changelog] │
|
||
├──────────────────────────────────────────────────────────────────────────────────────────────┤
|
||
│ Overview │
|
||
│ Latest Bundle Version: 1.3.0-rc1 Bundle Manifest Digest: sha256:abcd... │
|
||
│ Security Snapshot: 1 critical reachable | 0 high reachable | VEX coverage 62% │
|
||
│ Reachability Coverage: Image 100% | Build 78% | Runtime 35% │
|
||
│ │
|
||
│ Actions: [Create New Bundle Version] [Materialize to Env] [Create Promotion/Release] │
|
||
└──────────────────────────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
# 12.5 Screen — Create Bundle Version (Builder / Wizard)
|
||
|
||
### Formerly
|
||
|
||
* Implicit in:
|
||
|
||
* **Releases → + Create Release** (user picked components / versions ad-hoc)
|
||
* CI pipeline output (digest exists, but bundle composition logic is external/manual)
|
||
|
||
### Why changed like this
|
||
|
||
* You explicitly want:
|
||
|
||
* “microservice with digest becomes version X”
|
||
* “bundle includes variables derived from Vault/Consul for env”
|
||
* “bundle includes changelog per repository”
|
||
* This requires an explicit **builder** that:
|
||
|
||
* selects component versions (digests),
|
||
* computes changelog diffs,
|
||
* validates SBOM + reachability coverage readiness,
|
||
* produces an immutable **bundle version**.
|
||
|
||
### Screen graph (Mermaid)
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[Bundle Version Builder] --> S1[Step 1: Base Version]
|
||
A --> S2[Step 2: Select Component Versions]
|
||
A --> S3[Step 3: Config Contracts (vars required)]
|
||
A --> S4[Step 4: Changelog Preview (per repo)]
|
||
A --> S5[Step 5: Validate (policy + readiness)]
|
||
A --> S6[Step 6: Finalize → Create Bundle Version]
|
||
S6 --> BV[Bundle Version Detail]
|
||
```
|
||
|
||
### ASCII mock
|
||
|
||
```text
|
||
┌──────────────────────────────────────────────────────────────────────────────────────────────┐
|
||
│ Create Bundle Version — Platform Release │
|
||
│ Legacy: Releases ▸ +Create Release (implicit) │
|
||
├──────────────────────────────────────────────────────────────────────────────────────────────┤
|
||
│ Steps: (1) Base (2) Components (3) Config (4) Changelog (5) Validate (6) Finalize │
|
||
├──────────────────────────────────────────────────────────────────────────────────────────────┤
|
||
│ (1) Base Version │
|
||
│ Base: [ 1.2.3 ] (diff will be computed vs base) │
|
||
│ New version label: [ 1.3.0-rc1 ] │
|
||
│ Notes: [ Release candidate for next major version ] │
|
||
│ │
|
||
│ Next → │
|
||
└──────────────────────────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
# 12.6 Screen — Builder Step: Select Component Versions (digest-first → display version)
|
||
|
||
### Formerly
|
||
|
||
* Components were directly attached to a **Release** row; versions/digests were not first-class.
|
||
* Digest→version mapping usually lived in CI/repo tags and wasn’t visible in Stella.
|
||
|
||
### Why changed like this
|
||
|
||
* Digest-first is required for determinism; version labels help humans.
|
||
* This screen makes it explicit and auditable: **what digest** is being promoted and **why we call it version X**.
|
||
|
||
### Screen graph (Mermaid)
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
A[Select Component Versions] --> B[Pick from Component Catalog]
|
||
A --> C[Import latest from CI/Registry]
|
||
A --> D[Open Component Version Detail]
|
||
A --> E[Continue to Config Contracts]
|
||
```
|
||
|
||
### ASCII mock
|
||
|
||
```text
|
||
┌──────────────────────────────────────────────────────────────────────────────────────────────┐
|
||
│ Create Bundle Version — Step (2) Components │
|
||
│ Legacy: Release row “Components: N” (no explicit digest→version mapping UI) │
|
||
├──────────────────────────────────────────────────────────────────────────────────────────────┤
|
||
│ Repo-set: api-gw, user-svc, web-fe, worker │
|
||
│ │
|
||
│ ┌───────────────┬───────────────┬───────────────────────────┬─────────────┬──────────────────┐│
|
||
│ │ Component │ Display Ver. │ Digest (authoritative) │ SBOM Status │ Reachability ││
|
||
│ ├───────────────┼───────────────┼───────────────────────────┼─────────────┼──────────────────┤│
|
||
│ │ api-gateway │ 2.1.0 │ sha256:1111... │ OK │ Image+Build ││
|
||
│ │ user-service │ 3.0.0-rc1 │ sha256:2222... │ OK │ Image only (gap) ││
|
||
│ │ web-frontend │ 2.0.0 │ sha256:3333... │ OK │ Image+Runtime ││
|
||
│ │ worker │ 3.1.0 │ sha256:4444... │ PENDING │ — ││
|
||
│ └───────────────┴───────────────┴───────────────────────────┴─────────────┴──────────────────┘│
|
||
│ Actions: [Import Latest] [Open Component Detail] │
|
||
│ Gate note: “SBOM PENDING” will block finalize if policy requires SBOM for prod. │
|
||
└──────────────────────────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
# 12.7 Screen — Builder Step: Config Contracts (variables required by services)
|
||
|
||
### Formerly
|
||
|
||
* Config came from outside Stella or scattered across:
|
||
|
||
* Vault (secrets),
|
||
* Consul (KV),
|
||
* deployment manifests,
|
||
* Release Control env config.
|
||
|
||
### Why changed like this
|
||
|
||
* You want bundle to include “variables derived from Vault/Consul for this env”.
|
||
* To do that deterministically, Stella needs:
|
||
|
||
* a **contract**: what variables each service requires,
|
||
* a **binding**: where to source them per region/env.
|
||
|
||
> Design choice:
|
||
>
|
||
> * **Contracts live with the bundle/component** (what is needed).
|
||
> * **Bindings live with Release Control → Environment Inputs** (where it comes from in a region/env).
|
||
> This keeps “what” separate from “where”.
|
||
|
||
### Screen graph (Mermaid)
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[Config Contracts Step] --> B[View service variable requirements]
|
||
A --> C[Link to Env Bindings (Release Control)]
|
||
A --> D[Validate: missing bindings?]
|
||
A --> E[Continue to Changelog]
|
||
```
|
||
|
||
### ASCII mock
|
||
|
||
```text
|
||
┌──────────────────────────────────────────────────────────────────────────────────────────────┐
|
||
│ Create Bundle Version — Step (3) Config Contracts │
|
||
│ Legacy: N/A (new). Previously: env vars existed in Vault/Consul + manifests, not bundled. │
|
||
├──────────────────────────────────────────────────────────────────────────────────────────────┤
|
||
│ Variable requirements (by component) │
|
||
│ │
|
||
│ api-gateway │
|
||
│ - RATE_LIMIT_MAX (required) source: consul kv key: service/api-gw/rate_limit_max │
|
||
│ - JWT_PUBLIC_KEYS (required) source: vault path: secret/api-gw/jwt_keys │
|
||
│ │
|
||
│ user-service │
|
||
│ - AUTH_TIMEOUT_MS (required) source: consul kv key: service/user/auth_timeout_ms │
|
||
│ - DB_PASSWORD (required) source: vault path: secret/user/db_password │
|
||
│ │
|
||
│ Binding check (target env later): │
|
||
│ US-East/us-prod: 2 missing bindings (DB_PASSWORD, JWT_PUBLIC_KEYS) → will block materialize │
|
||
│ Link: [Open Release Control → us-prod → Inputs] │
|
||
└──────────────────────────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
# 12.8 Screen — Builder Step: Changelog Preview (per repository)
|
||
|
||
### Formerly
|
||
|
||
* Changelog was manual or external (GitHub/GitLab release notes), not attached to the release object in Stella.
|
||
|
||
### Why changed like this
|
||
|
||
* You require “bundle along with change log, per repository”.
|
||
* This gives reviewers and auditors a deterministic view:
|
||
|
||
* “what changed in api-gw between digest A and digest B”
|
||
* tied to the exact component versions.
|
||
|
||
### Screen graph (Mermaid)
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
A[Changelog Preview] --> B[Repo diff summary per component]
|
||
A --> C[Expand commit/PR list]
|
||
A --> D[Export changelog]
|
||
A --> E[Continue to Validate]
|
||
```
|
||
|
||
### ASCII mock
|
||
|
||
```text
|
||
┌──────────────────────────────────────────────────────────────────────────────────────────────┐
|
||
│ Create Bundle Version — Step (4) Changelog (per repo) │
|
||
│ Legacy: N/A (new). Previously: release notes lived in SCM/CI tools, not in Stella. │
|
||
├──────────────────────────────────────────────────────────────────────────────────────────────┤
|
||
│ Base: 1.2.3 → New: 1.3.0-rc1 │
|
||
│ │
|
||
│ api-gateway: 12 commits (3 PRs) │
|
||
│ • PR #431: add rate limiting feature │
|
||
│ • PR #428: fix header parsing bug │
|
||
│ │
|
||
│ user-service: 4 commits (1 PR) │
|
||
│ • PR #77: critical fix for user authentication timeout │
|
||
│ │
|
||
│ web-frontend: 2 commits │
|
||
│ worker: 0 commits │
|
||
│ │
|
||
│ [Export as Markdown] [Attach to Bundle Version Notes] │
|
||
└──────────────────────────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
# 12.9 Screen — Builder Step: Validate (policy readiness + SBOM + feeds + reachability)
|
||
|
||
### Formerly
|
||
|
||
* Validation was split:
|
||
|
||
* Approvals page mentions policy + reachability,
|
||
* Security pages show findings,
|
||
* Operations show feeds/job status,
|
||
* none were unified at “bundle creation”.
|
||
|
||
### Why changed like this
|
||
|
||
* Bundle version should be created as an auditable artifact with a clear “ready for prod?” signal.
|
||
* This is where we prevent “unknown SBOM state” from entering promotion pipeline.
|
||
|
||
### Screen graph (Mermaid)
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[Validate Bundle Version] --> B[Policy Gate Evaluation Snapshot]
|
||
A --> C[SBOM & Findings Readiness]
|
||
A --> D[Hybrid Reachability Coverage Check]
|
||
A --> E[Feed Freshness / Integration Health]
|
||
A --> F[Finalize]
|
||
```
|
||
|
||
### ASCII mock
|
||
|
||
```text
|
||
┌──────────────────────────────────────────────────────────────────────────────────────────────┐
|
||
│ Create Bundle Version — Step (5) Validate │
|
||
│ Legacy: distributed across Approvals + Security + Ops + Integrations │
|
||
├──────────────────────────────────────────────────────────────────────────────────────────────┤
|
||
│ Policy baseline: Prod (US-East) │
|
||
│ │
|
||
│ Gates │
|
||
│ ✓ All component digests resolved │
|
||
│ ✗ SBOM scan pending: worker sha256:4444... (required for prod) │
|
||
│ ✓ CVE feeds fresh (NVD: synced 1h ago, OSV: synced 20m ago) │
|
||
│ ⚠ Hybrid reachability coverage: runtime evidence 35% (policy: warn, not block) │
|
||
│ │
|
||
│ Action required: [Trigger SBOM Scan Now] (or change component selection) │
|
||
└──────────────────────────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
# 12.10 Screen — Bundle Version Detail (immutable snapshot + evidence pointers)
|
||
|
||
### Formerly
|
||
|
||
* Not a first-class object. Closest:
|
||
|
||
* Release detail (not shown in PoC screenshots) + Evidence exports
|
||
* But there was no immutable “bundle version” with its own digest.
|
||
|
||
### Why changed like this
|
||
|
||
* This is the deterministic record that promotions reference:
|
||
|
||
* It is what you **replay/verify** against,
|
||
* what you **export evidence** for,
|
||
* what you diff between versions.
|
||
|
||
### Screen graph (Mermaid)
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[Bundle Version Detail] --> B[Manifest Tab (digests + versions)]
|
||
A --> C[Security Snapshot Tab]
|
||
A --> D[Reachability Coverage Tab]
|
||
A --> E[Changelog Tab]
|
||
A --> F[Evidence Tab (DSSE/provenance links)]
|
||
A --> G[Promote/Materialize Actions]
|
||
A --> H[Diff vs previous version]
|
||
```
|
||
|
||
### ASCII mock
|
||
|
||
```text
|
||
┌──────────────────────────────────────────────────────────────────────────────────────────────┐
|
||
│ Bundle Version: Platform Release 1.3.0-rc1 │
|
||
│ Legacy: N/A (new). Previously: release rows mixed composition + promotion. │
|
||
├──────────────────────────────────────────────────────────────────────────────────────────────┤
|
||
│ Bundle manifest digest: sha256:abcd... Created: Jan 11, 2026 by ci-pipeline │
|
||
│ Base version: 1.2.3 Diff: +2 components changed, +16 commits total │
|
||
│ │
|
||
│ Tabs: [Manifest] [Security] [Reachability] [Changelog] [Evidence] [Promotions] [Diff] │
|
||
├──────────────────────────────────────────────────────────────────────────────────────────────┤
|
||
│ Manifest (digest-first) │
|
||
│ api-gateway v2.1.0 sha256:1111... SBOM OK │
|
||
│ user-service v3.0.0-rc1 sha256:2222... SBOM OK │
|
||
│ web-frontend v2.0.0 sha256:3333... SBOM OK │
|
||
│ worker v3.1.0 sha256:4444... SBOM OK │
|
||
│ │
|
||
│ Actions: [Materialize to Env] [Create Promotion] [Export Evidence Pack] │
|
||
└──────────────────────────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
# 12.11 Screen — Component Catalog (Service Versions)
|
||
|
||
### Formerly
|
||
|
||
* Implicit:
|
||
|
||
* registry contains digests
|
||
* CI contains build versions
|
||
* Stella UI doesn’t centralize digest→version mapping, SBOM state, reachability sources
|
||
|
||
### Why changed like this
|
||
|
||
* You need a stable bridge:
|
||
|
||
* digest-first identity,
|
||
* human-friendly version labels,
|
||
* SBOM + reachability metadata used by bundle builder and approvals.
|
||
|
||
### Screen graph (Mermaid)
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
A[Component Catalog] --> B[Component Version Detail]
|
||
A --> C[Import from Registry/CI]
|
||
A --> D[Manage Version Mapping Rules]
|
||
A --> E[Link to bundles using this component]
|
||
```
|
||
|
||
### ASCII mock
|
||
|
||
```text
|
||
┌──────────────────────────────────────────────────────────────────────────────────────────────┐
|
||
│ Releases ▸ Components (Service Versions) │
|
||
│ Legacy: N/A (new). Previously: versions lived in CI/registry only. │
|
||
├──────────────────────────────────────────────────────────────────────────────────────────────┤
|
||
│ Filter: Repo [All] SBOM [All] Reachability [Any] Deployed [Any] │
|
||
│ Actions: [Import Latest] [Sync Now] │
|
||
├──────────────────────────────────────────────────────────────────────────────────────────────┤
|
||
│ ┌───────────────┬───────────────┬───────────────────────┬──────────┬────────────────────────┐│
|
||
│ │ Component │ Version Label │ Digest │ SBOM │ Reachability Sources ││
|
||
│ ├───────────────┼───────────────┼───────────────────────┼──────────┼────────────────────────┤│
|
||
│ │ api-gateway │ 2.1.0 │ sha256:1111... │ OK │ image, build ││
|
||
│ │ user-service │ 3.0.0-rc1 │ sha256:2222... │ OK │ image ││
|
||
│ │ web-frontend │ 2.0.0 │ sha256:3333... │ OK │ image, runtime ││
|
||
│ └───────────────┴───────────────┴───────────────────────┴──────────┴────────────────────────┘│
|
||
└──────────────────────────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
# 12.12 Screen — Component Version Detail (SBOM + findings + hybrid reachability)
|
||
|
||
### Formerly
|
||
|
||
* SBOM/finding visibility existed, but:
|
||
|
||
* Findings list was global and empty in PoC,
|
||
* Reachability concept existed in approvals but not clearly traceable to image/build/runtime sources,
|
||
* No single “component version truth page”.
|
||
|
||
### Why changed like this
|
||
|
||
* This screen is the forensic anchor:
|
||
|
||
* if a bundle is blocked, you drill into the **component version** to see why (SBOM, CVEs, reachability evidence sources).
|
||
|
||
### Screen graph (Mermaid)
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[Component Version Detail] --> B[SBOM Summary]
|
||
A --> C[Findings (reachable/not)]
|
||
A --> D[Reachability (image/build/runtime)]
|
||
A --> E[Provenance/Attestations]
|
||
A --> F[Used-in Bundles]
|
||
A --> G[Deployed-in Environments]
|
||
```
|
||
|
||
### ASCII mock
|
||
|
||
```text
|
||
┌──────────────────────────────────────────────────────────────────────────────────────────────┐
|
||
│ Component Version: user-service v3.0.0-rc1 │
|
||
│ Digest: sha256:2222... │
|
||
│ Legacy: N/A (new). Previously: info split across registry + approvals + security views. │
|
||
├──────────────────────────────────────────────────────────────────────────────────────────────┤
|
||
│ Tabs: [SBOM] [Findings] [Reachability] [Provenance] [Used-in Bundles] [Deployed-in Envs] │
|
||
├──────────────────────────────────────────────────────────────────────────────────────────────┤
|
||
│ Findings snapshot │
|
||
│ Critical reachable: 0 High reachable: 0 High not reachable: 2 │
|
||
│ VEX: statement present for CVE-XXXX (not exploitable: config) │
|
||
│ │
|
||
│ Reachability coverage │
|
||
│ Image evidence: ✓ Build evidence: ✗ Runtime evidence: ✗ │
|
||
│ Note: policy may warn or block based on baseline. │
|
||
└──────────────────────────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
# 12.13 Screen — Materialize Bundle Version to Environment (resolve Vault/Consul + produce deployment plan)
|
||
|
||
### Formerly
|
||
|
||
* No explicit step. Operators/CI manually resolved env inputs and then deployed.
|
||
* Release Control had environment config; Integrations had Vault; but no “bundle→env resolved view”.
|
||
|
||
### Why changed like this
|
||
|
||
* Your requirement explicitly: “bundle includes variables derived from vaults and consul for this env”.
|
||
* This screen is where the bundle becomes deployable in a specific **region/env**:
|
||
|
||
* resolve required variables,
|
||
* detect missing bindings,
|
||
* produce a deterministic deployment plan,
|
||
* then create a promotion/approval.
|
||
|
||
### Screen graph (Mermaid)
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[Materialize Bundle → Environment] --> B[Select Region/Env]
|
||
A --> C[Resolve Inputs (Vault/Consul)]
|
||
A --> D[Show Missing/Overrides]
|
||
A --> E[Generate Deployment Plan]
|
||
A --> F[Create Promotion/Approval]
|
||
A --> G[Optional: Build AirGap Artifact]
|
||
```
|
||
|
||
### ASCII mock
|
||
|
||
```text
|
||
┌──────────────────────────────────────────────────────────────────────────────────────────────┐
|
||
│ Materialize: Platform Release 1.3.0-rc1 → US-East / us-prod │
|
||
│ Legacy: N/A (new). Previously: env vars resolved outside Stella, deployment was external. │
|
||
├──────────────────────────────────────────────────────────────────────────────────────────────┤
|
||
│ Inputs resolution │
|
||
│ ✓ consul: service/api-gw/rate_limit_max = 500 │
|
||
│ ✓ vault: secret/api-gw/jwt_keys = (sealed) │
|
||
│ ✗ vault: secret/user/db_password = MISSING (binding not configured) │
|
||
│ │
|
||
│ Result │
|
||
│ Status: BLOCKED (cannot materialize) │
|
||
│ Fix: [Open Release Control → US-East/us-prod → Inputs] │
|
||
│ │
|
||
│ When resolved: [Generate Deployment Plan] [Create Promotion Request] [Build AirGap Bundle] │
|
||
└──────────────────────────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
# 12.14 Screen — Changelog (per repo) for a Bundle Version (drilldown)
|
||
|
||
### Formerly
|
||
|
||
* External to Stella (SCM release notes / PR list / commit diff)
|
||
|
||
### Why changed like this
|
||
|
||
* Auditors and approvers need changelog tied to exact digests.
|
||
* This page also prevents “bundle label changed but nothing actually changed” confusion.
|
||
|
||
### Screen graph (Mermaid)
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
A[Bundle Version Changelog] --> B[Repo-level diff]
|
||
A --> C[Commit/PR detail]
|
||
A --> D[Export (md/pdf)]
|
||
A --> E[Link to approvals referencing this version]
|
||
```
|
||
|
||
### ASCII mock
|
||
|
||
```text
|
||
┌──────────────────────────────────────────────────────────────────────────────────────────────┐
|
||
│ Changelog — Platform Release 1.3.0-rc1 (vs 1.2.3) │
|
||
│ Legacy: N/A (new). Previously: changelog was not a Stella object. │
|
||
├──────────────────────────────────────────────────────────────────────────────────────────────┤
|
||
│ api-gateway │
|
||
│ + PR #431 rate limiting feature │
|
||
│ + PR #428 header parsing fix │
|
||
│ │
|
||
│ user-service │
|
||
│ + PR #77 auth timeout critical fix │
|
||
│ │
|
||
│ web-frontend │
|
||
│ + commit 8f2a... update UI │
|
||
│ │
|
||
│ Exports: [Markdown] [Attach to Evidence Packet] │
|
||
└──────────────────────────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
# 12.15 Screen — Optional integration: Build AirGap Bundle (linking to existing Ops screen)
|
||
|
||
### Formerly
|
||
|
||
* **Operations → Feeds → AirGap Bundles** (tab), disconnected from release objects.
|
||
|
||
### Why changed like this
|
||
|
||
* AirGap artifacts should be generated *from a specific bundle version + environment materialization*.
|
||
* Keep the existing Ops screen (for storage/transfer), but **initiate and trace** it from the bundle context.
|
||
|
||
### Screen graph (Mermaid)
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
A[Bundle Version Detail] --> B[Materialize to Env]
|
||
B --> C[Build AirGap Bundle]
|
||
C --> D[Operations → AirGap Bundles (tracking)]
|
||
D --> E[Download/Transfer/Verify]
|
||
```
|
||
|
||
### ASCII mock (in-bundle launch)
|
||
|
||
```text
|
||
┌──────────────────────────────────────────────────────────────────────────────────────────────┐
|
||
│ Build AirGap Bundle │
|
||
│ Legacy: Ops ▸ Feeds ▸ AirGap Bundles (no release linkage) │
|
||
├──────────────────────────────────────────────────────────────────────────────────────────────┤
|
||
│ Source: Platform Release 1.3.0-rc1 (bundle digest sha256:abcd...) │
|
||
│ Target: US-East / us-prod │
|
||
│ Includes: images (14) + manifests + resolved config overlays + checksums │
|
||
│ │
|
||
│ [Start Build] → tracking will appear in Ops ▸ AirGap Bundles │
|
||
└──────────────────────────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## What this changes elsewhere (minimal but necessary touchpoints)
|
||
|
||
To preserve functionality yet make it “Stella Ops way”, two UI pivots must happen:
|
||
|
||
1. **Releases list** (`/releases`)
|
||
|
||
* continues to exist, but each release row becomes:
|
||
**Promotion of {Bundle Version} to {Env path}**
|
||
* “Components” column becomes derived from bundle version.
|
||
|
||
2. **Approvals** (`/approvals`)
|
||
|
||
* approvals reference bundle version digest + materialization result (inputs resolved / missing).
|
||
|
||
These are cross-screen wiring changes; the *new screens in this pack* provide the missing first-class objects required to make that consistent and auditable.
|
||
|
||
---
|
||
|
||
If you want the next pack, I can do **Pack 13**: “Releases + Approvals screens updated to reference Bundle Versions everywhere” (Mermaid graphs + ASCII mocks + legacy naming).
|