railiance-cluster/workplans/RAIL-BS-WP-0006-staged-promotion-lifecycle.md

---
id: RAIL-BS-WP-0006
type: workplan
title: "Staged Promotion Lifecycle"
domain: railiance
repo: railiance-cluster
status: active
owner: railiance
topic_slug: railiance
repo_goal_id: "6ea441f7-7fe3-4598-922b-38baf20c0580"
state_hub_workstream_id: "cb72d3ba-1863-43c2-a2a5-49ac75fc2603"
created: "2026-02-24"
updated: "2026-05-03"
---

# Staged Promotion Lifecycle

## Goal

Design and implement the three-stage deployment lifecycle as the core
Railiance application promotion pattern:

1. Stage 1: local development and validation.
2. Stage 2: canary on production infrastructure.
3. Stage 3: full production promotion with rollback.

This lifecycle should become the repeatable path for native Railiance apps and
third-party upstream applications wrapped by a Railiance overlay repo.

## Why This Belongs Before Forgejo

Forgejo will become critical production infrastructure. Before moving the
source forge itself, Railiance needs a well-defined promotion lifecycle so the
Forgejo deployment, Actions runners, package registry, and future upgrades can
move through the same staged gates as every other important workload.

## Boundary

This workplan lives in `railiance-cluster` because it defines cluster runtime
promotion mechanics and the canonical handoff between local validation,
canary deployment, and production routing.

Expected cross-repo handoffs:

- `railiance-enablement`: developer-facing CLI templates and CI workflow
  conventions.
- `railiance-platform`: shared platform dependencies used by canaries.
- `railiance-apps`: application Helm values and workload-specific promotion
  definitions.

## Tasks

### T01 - Write deployment lifecycle specification

```task
id: RAIL-BS-WP-0006-T01
status: todo
priority: high
state_hub_task_id: "fbfc341f-8ccb-4950-a85d-3e59c4f5b87f"
```

Write `docs/deployment-lifecycle.md`.

The spec should define:

- Stage 1, Stage 2, and Stage 3 semantics.
- Required checks before each stage.
- Canary acceptance gates.
- Rollback expectations.
- Human approval gates for production-critical workloads.

**Done when:** the lifecycle is clear enough to apply to Forgejo as a later
production workload.

---

### T02 - Define railiance directory schema and app.toml contract

```task
id: RAIL-BS-WP-0006-T02
status: todo
priority: high
state_hub_task_id: "523cf928-bb0e-4109-a172-abf029c62885"
```

Define the repository-local `railiance/` directory schema and `app.toml`
contract for native and third-party applications.

Minimum contract:

- App identity and ownership.
- Stage definitions.
- Required platform dependencies.
- Health checks and observability endpoints.
- Promotion and rollback commands.
- Secret references without plaintext secret values.

**Done when:** a repo can declare how it moves through the Railiance promotion
lifecycle without bespoke instructions.

---

### T03 - Overlay repo pattern and creation script

```task
id: RAIL-BS-WP-0006-T03
status: todo
priority: medium
state_hub_task_id: "7cd378f2-0319-407a-9ce7-2c6d1a6d6d24"
```

Design the overlay repo pattern for third-party upstream applications and add
`create_railiance_overlay_repo.sh` or equivalent tooling.

The pattern should keep upstream code and Railiance deployment concerns cleanly
separated while still allowing reproducible promotion.

**Done when:** a third-party app can be wrapped without forking deployment
logic into the upstream repository.

---

### T04 - railiance run command

```task
id: RAIL-BS-WP-0006-T04
status: todo
priority: high
state_hub_task_id: "95c3311b-04bb-4c83-bda3-47958217b665"
```

Implement the Stage 1 `railiance run` command for local development and
validation.

Expected behavior:

- Read `railiance/app.toml`.
- Start or validate the local development target.
- Run defined local health checks.
- Emit a machine-readable result suitable for later promotion gates.

**Done when:** at least one representative app can complete Stage 1 locally.

---

### T05 - Canary Helm chart template

```task
id: RAIL-BS-WP-0006-T05
status: todo
priority: high
state_hub_task_id: "47b8cd47-99c7-4f31-a147-ea16afde7217"
```

Create the Stage 2 canary Helm chart template.

Minimum requirements:

- Stable and canary release identities.
- Weighted routing or equivalent traffic split through the chosen ingress
  path.
- Prometheus-compatible annotations.
- Resource limits appropriate for single-node and future ThreePhoenix use.
- Rollback-safe values layout.

**Done when:** a canary deployment can be created without hand-editing cluster
resources.

---

### T06 - railiance deploy --stage 2 and observation tooling

```task
id: RAIL-BS-WP-0006-T06
status: todo
priority: medium
state_hub_task_id: "6a5c7422-fcb1-49d1-8153-e891bd1c27fa"
```

Implement Stage 2 deployment and observation commands.

Expected behavior:

- Deploy the canary from declared app metadata.
- Show rollout state, pod health, ingress/routing state, and key metrics.
- Fail closed when prerequisites or health gates are missing.

**Done when:** Stage 2 can be run and observed from a repeatable command path.

---

### T07 - railiance promote, rollback, and onboarding guide

```task
id: RAIL-BS-WP-0006-T07
status: todo
priority: medium
state_hub_task_id: "476198f6-0049-4ac4-9593-6723c86c9602"
```

Implement Stage 3 promotion and rollback commands, then write the reference
onboarding guide.

Expected output:

- `railiance promote` for controlled production promotion.
- `railiance rollback` for reverting to the previous stable version.
- A guide showing how a representative app adopts the lifecycle.
- Explicit human approval points for critical infrastructure workloads.

**Done when:** a representative app can move Stage 1 -> Stage 2 -> Stage 3 and
back through rollback using documented commands.

## Dependencies

This workplan should be done before the Forgejo production cutover. It can run
in parallel with preparatory ThreePhoenix design, but its Stage 2/3 behavior
should be validated against the intended ThreePhoenix cluster model.