railiance-forge/INTENT.md

INTENT

This file captures why this repository exists, the direction it is moving toward, and the kind of system it is meant to become. It is intentionally aspirational and stable, not a description of current implementation.

---

One-liner

The forge capability - turning source hosting, registries, and automation runners into dependable Railiance release infrastructure.

---

Why This Exists

Applications need more than a runtime to ship safely. They need a governed place for source hosting, package and image publication, CI runner substrate, release artifact retention, and operational evidence.

Before this repo, forge concerns were spread across S4 enablement and S5 application deployment work. That made it hard to tell who owned Gitea, Forgejo, package registries, Actions runners, registry storage, and artifact promotion evidence.

This layer exists to make those responsibilities explicit and operable.

---

The Mission

Where we are going.

To become the canonical home for Railiance forge and artifact infrastructure

• current Gitea operation, future Forgejo migration, container and package registries, forge-backed automation runner substrate, artifact lifecycle, and forge operational evidence.

This means:

• Source forge runtime is operated through a clear repo-owned contract
• Package and image registries have retention, restore, and capacity posture
• CI runners are owned separately from reusable CI/CD templates
• S5 applications can consume artifacts without owning forge internals
• Future Forgejo cutover can happen without confusing it with app deployment

---

Core Principles

1. Forge Runtime, Not Application Releases

Own the forge and artifact infrastructure. Do not own user-facing application release charts or application source code.

2. Artifacts With Evidence

Images, packages, and release assets should carry enough provenance and inspection evidence for downstream releases to trust them.

3. Runner Substrate, Not Every Workflow

Own the runner infrastructure and credentials. Reusable workflow templates belong in S4 enablement, and app-specific workflows belong near the app or its release repo.

4. Stable Handoffs

Consumers should depend on stable forge capabilities: source hosting, Git SSH, container registry, package registry, workflow execution, and artifact promotion evidence.

5. Restore Before Trust

Forge data is operationally critical. Source repos, packages, registry blobs, and runner state need explicit backup and restore posture.

6. Current Gitea, Future Forgejo

Gitea is the current workload; Forgejo is the intended production direction. The repo should support both the current operating state and clean future cutover planning.

---

What This Is (Conceptually)

This layer is:

• a source forge operations layer
• an artifact registry layer
• an automation runner substrate layer
• a release evidence provider
• a bridge between S4 delivery paths and S5 application releases

---

What This Is Not

This layer is not:

• the infrastructure substrate beneath Railiance
• the Kubernetes runtime
• the shared platform-services layer
• the generic CI/CD template and developer portal layer
• the application release and runbook layer
• the source-code home for business applications
• a runtime secret custody authority

It is the forge and artifact infrastructure that lets the rest of Railiance build, publish, automate, and consume releases.

---

Placement

This repository previously described itself as "the forge layer". The OAS Stack dimension defines five levels (S1-S5) and forge is not one of them, so that description left it unplaced - which is how layer boundaries erode.

Placement was decided 2026-08-11 (hub decision d151d817):

• the Forgejo workload becomes rapp-forgejo, a managed workload package
• the consumer-facing contract - reusable workflow expectations for runner labels, registry interfaces, package credentials, and artifact evidence - belongs to S4 railiance-enablement
• this repo remains the operational provider for the live forge, registry, runner substrate, retention, custody references, and operating evidence until a separately approved migration changes that boundary

A retirement hypothesis was tested and rejected: this repo and helix-forge are different lineages, not one maturing into the other. helix-forge is methodological (capability-first ecosystem, OAS dimensions, VSM vocabulary); this repo is operational. Retiring it would orphan responsibilities nothing else owns.

This split does not require a physical merge: enablement owns the paved consumer path, while this repo owns the capability that path consumes. The Forgejo workload is expected to become rapp-forgejo without moving its operator contract into enablement. See railiance-platform/ArchitectureBlueprint.md section 5.2.

---

Direction of Evolution

This layer is expected to evolve toward:

• Clean extraction of current Gitea operation from railiance-apps
• Explicit Forgejo migration and production cutover planning
• Versioned artifact lifecycle and retention policy
• Runner placement, label, credential, and secret-access policy
• Backup and restore evidence for source, package, and registry data
• Fabric declarations for forge capabilities and dependencies
• Self-evidencing forge health and readiness checks

---

Guiding Question

How can Railiance make source hosting, artifact publication, and automation execution dependable enough that application releases can consume them without owning them?