---
id: RAILIANCE-WP-0005
type: workplan
title: "S5 app release readiness and scope alignment"
domain: railiance
repo: railiance-apps
status: ready
owner: codex
topic_slug: railiance
planning_priority: medium
created: "2026-06-04"
updated: "2026-06-04"
state_hub_workstream_id: "685f1c18-33c0-400d-a2b1-e1dae0f27c3e"
---

# S5 app release readiness and scope alignment

## Context

The 2026-06-04 review of `SCOPE.md` against the actual repository
implementation found that `railiance-apps` has moved beyond "Gitea Helm values"
and now owns the repeatable S5 application release surface: Gitea registry
enablement, the `vergabe-teilnahme` Helm release, operator guardrails, and
deployment runbooks.

The same review found several gaps:

- `INTENT.md` is missing, so purpose and scope are collapsed into one document.
- The `vergabe-teilnahme` runbook still contains stale image-promotion guidance
  tied to the old local `issue-core` build context.
- First-app lessons are documented, but there is no reusable checklist for the
  next S5 app release.
- Gitea package storage and app database backup responsibilities need clearer
  contracts with platform-layer work.
- The server-side dry-run workflow does not state its live-cluster/CRD
  prerequisites clearly enough for a future runner.

This workplan turns those scope gaps into the next improvement strand.

## T01 - Write `INTENT.md`

```task
id: RAILIANCE-WP-0005-T01
status: done
priority: high
state_hub_task_id: "af15d202-c013-48b1-8522-671477e31381"
```

Create `INTENT.md` for `railiance-apps`.

It should explain:

- why this repo exists as the S5 application deployment surface;
- what problem it solves for operators and source app repos;
- what it intentionally does not own across S1-S4 boundaries;
- how Gitea, package registry enablement, `vergabe-teilnahme`, and future S5
  apps fit together;
- how workplan files relate to State Hub workstreams and task rows.

Done when `INTENT.md` stands on its own and `SCOPE.md` can reference it instead
of carrying all purpose language itself.

---

## T02 - Normalize app image promotion and package registry docs

```task
id: RAILIANCE-WP-0005-T02
status: todo
priority: high
state_hub_task_id: "f8f63edb-a7ef-4692-8b01-66402d296cbb"
```

Update app promotion docs after the `issue-core` package handoff is complete.

Focus areas:

- remove stale references to the old `--build-context issue-core=...` path from
  `docs/vergabe-teilnahme.md`;
- document the package-registry credential path for private Python package
  installs without committing tokenized index URLs;
- state when `vergabe-teilnahme/uv.lock` must be regenerated in the source repo;
- keep `docs/gitea-package-registry.md` focused on the S5 registry endpoint and
  cross-link source-repo release docs instead of duplicating them.

Done when the Railiance operator docs describe the portable image promotion path
and no active runbook tells an operator to rely on a sibling repo checkout.

---

## T03 - Create a reusable S5 app onboarding checklist

```task
id: RAILIANCE-WP-0005-T03
status: todo
priority: medium
state_hub_task_id: "4eab93a9-ad1b-46ca-97ef-18a059f64ab5"
```

Turn the `vergabe-teilnahme` deployment lessons into a reusable checklist for
the next S5 app.

The checklist should cover:

- chart and values layout;
- ingress and TLS ownership;
- health probe Host headers for framework apps;
- database secret handoff and URL-encoding guidance;
- image registry naming and pull verification;
- runbook sections every S5 app should ship;
- smoke-test pattern using persistent pods plus `kubectl exec`;
- State Hub workplan and task-sync expectations.

Done when a new app can start from the checklist without reading all historical
workplans first.

---

## T04 - Define app data backup and restore handoffs

```task
id: RAILIANCE-WP-0005-T04
status: todo
priority: high
state_hub_task_id: "299d9623-3a54-4e85-9a70-016e8356c3d9"
```

Clarify where S5 app data durability begins and ends.

Cover at least:

- Gitea package blobs on the shared Gitea PVC;
- `vergabe_db` on the shared `apps-pg` CNPG cluster;
- responsibility split between S5 runbooks and `railiance-platform` backup
  controllers;
- minimum restore-drill evidence S5 app operators need before promoting an app
  beyond smoke-test usage;
- how to file or link platform-layer workplans when the durability gap is not
  local to this repo.

Done when `SCOPE.md` and app runbooks clearly separate S5 release ownership from
S3 backup implementation while still giving operators an actionable restore
readiness gate.

---

## T05 - Make manifest dry-run workflow prerequisites explicit

```task
id: RAILIANCE-WP-0005-T05
status: todo
priority: medium
state_hub_task_id: "6cf0e662-d7e2-48b1-b1f2-c7636240dd81"
```

Document and, where useful, encode the assumptions behind
`.gitea/workflows/manifest-server-dry-run.yaml` and
`make k8s-server-dry-run`.

Questions to answer:

- Does the workflow expect a live representative cluster?
- Which CRDs must already exist for server-side dry-run to be meaningful?
- What credentials or runner placement are required?
- What should happen when a runner has no cluster access?
- Which failures are release-blocking versus local operator setup issues?

Done when a future operator can tell whether the workflow is ready to enforce
PR checks or still needs runner/cluster preparation.

---

## T06 - Define Gitea package registry storage and retention posture

```task
id: RAILIANCE-WP-0005-T06
status: todo
priority: medium
state_hub_task_id: "382ba252-0f54-45fa-8e33-e656f4472341"
```

Document the operating posture for Gitea package storage while Gitea remains the
active forge.

Include:

- current PVC, size, and package blob location;
- expected retention approach for smoke-test images and Python wheels;
- cleanup procedure for superseded test tags;
- alert or inspection command for package storage growth;
- handoff to platform backup/restore work when package data becomes production
  critical.

Done when registry growth is no longer only a note in
`docs/gitea-container-registry.md`.