SCOPE

This file defines what railiance-forge owns, when to use it, and where its boundaries stop.

Last reviewed: 2026-06-05

One-liner

Forge and artifact infrastructure for Railiance: current Gitea operation, future Forgejo migration, container and package registries, Actions runner substrate, artifact lifecycle, and forge operational evidence.

Core Idea

railiance-forge separates forge responsibilities from S4 developer enablement and S5 application releases.

The practical contract is:

lower layers provide servers, Kubernetes runtime, databases, storage, and secret custody;
this repo owns the source forge runtime and artifact publication surface;
railiance-enablement owns reusable CI/CD templates and developer paved paths;
railiance-apps consumes forge artifacts and deploys user-facing workloads.

Canonical registry operation docs and read-only forge checks now live here. Deploy-capable Gitea Helm/SOPS/manifests also live here now; railiance-apps keeps only transitional compatibility wrappers for old operator entry points.

In Scope

Current Gitea operation and future Forgejo migration/cutover planning.
Source forge deployment configuration and runbooks.
Container registry and package registry enablement.
Registry storage posture, cleanup, retention, and restore readiness.
Forge-backed Actions runner substrate:
- runner deployment ownership;
- runner labels and placement;
- runner credential and secret-access boundaries.
Artifact publication evidence used by downstream release workflows:
- image tags;
- package versions;
- commit SHA provenance;
- promotion and smoke evidence.
Forge observability and operator checks:
- web endpoint health;
- Git SSH health;
- registry/package endpoint health;
- runner health;
- storage growth inspection.
Fabric declarations for forge capabilities, interfaces, and dependencies.
Repo-local workplan files under workplans/.

Out of Scope

OS provisioning and host hardening: railiance-infra.
Kubernetes runtime primitives, ingress controllers, and cluster addon installation: railiance-cluster.
Shared databases, object storage, caches, and runtime secret custody: railiance-platform.
Generic CI/CD templates, SDKs, buildpacks, and developer portal surfaces: railiance-enablement.
User-facing application release charts, app runbooks, migrations, and smoke tests: railiance-apps.
Application source code, package metadata, and image build definitions in source repos.
Secret value custody. This repo may reference secret names and approved delivery paths, but it must not commit decrypted secret material.

Relevant When

Operating or upgrading Gitea as the current Railiance forge.
Planning or executing a Forgejo migration or cutover.
Enabling or debugging container/package registry behavior.
Defining artifact retention, cleanup, provenance, or restore posture.
Deploying or operating forge-backed Actions runners.
Deciding whether a workflow issue is runner substrate, reusable template, or app-specific release logic.
Declaring forge capabilities in Railiance Fabric.

Not Relevant When

The work is an application release chart or app-specific runbook.
The work is a generic workload template or SDK.
The work is platform database provisioning or object-storage operation.
The work is Kubernetes runtime installation or ingress controller ownership.
The work is application source-code behavior.
The work requires live secret values outside approved custody paths.

Current State

Status: active forge extraction.
Implementation: repository contract, registry docs, initial operating contracts, deploy-capable Gitea files, and operator targets are present.
Stability: emerging but non-disruptive; files moved without any Helm deploy, SOPS decryption, or Kubernetes apply.
Usage: canonical reference point for forge and registry responsibilities currently transitioning out of railiance-apps.

Known starting point:

railiance-forge owns Gitea Helm values, registry overlays, ingress, operating contracts, and deploy/status entry points.
railiance-apps keeps app release ownership and transitional compatibility wrappers for old Gitea commands.
railiance-enablement owns the intent for delivery templates and developer paved paths, but not forge runtime operation.
railiance-forge should absorb forge runtime and artifact infrastructure without moving S5 app release ownership.

How It Fits

Upstream dependencies: railiance-infra, railiance-cluster, and railiance-platform.
Adjacent collaborators: railiance-enablement for reusable CI/CD paths and railiance-apps for consuming release artifacts in app deployments.
Downstream consumers: source repos, app release repos, operators, and Railiance users relying on source hosting and published artifacts.

Terminology

Preferred terms: forge, source forge, artifact registry, package registry, runner substrate, release evidence.
Also known as: Gitea/Forgejo operations, release infrastructure.
Potentially confusing terms: "workflow template" belongs in S4 enablement; "runner substrate" belongs here; "app release workflow" belongs near the app or S5 release surface.

railiance-apps - consumes forge artifacts in S5 app releases and keeps transitional pointers/wrappers for old Gitea paths.
railiance-enablement - owns reusable CI/CD templates, SDKs, buildpacks, and developer portal paths.
railiance-platform - provides database, storage, backup, and runtime secret services consumed by forge workloads.
railiance-cluster - provides Kubernetes runtime and cluster-level addons.
railiance-fabric - should model forge capabilities, interfaces, providers, and consumers.

Getting Oriented

Read AGENTS.md for session protocol and State Hub conventions.
Read INTENT.md for stable purpose.
Read this file for scope and boundaries.
Read active files in workplans/.
For registry operations, read docs/gitea-container-registry.md and docs/gitea-package-registry.md.
For migration context, read /home/worsch/railiance-apps/workplans/RAILIANCE-WP-0006-railiance-forge-extraction.md.

Provided Capabilities

type: infrastructure
title: Railiance source forge operation
description: Operate the current Gitea source forge and plan future Forgejo migration/cutover as dedicated Railiance forge infrastructure.
keywords: [railiance, forge, gitea, forgejo, source-hosting, git]

type: infrastructure
title: Railiance artifact registry operation
description: Own container and package registry enablement, retention, restore posture, and release artifact evidence for Railiance consumers.
keywords: [registry, container-image, python-package, artifact, retention, provenance]

type: operations
title: Forge automation runner substrate
description: Define and operate forge-backed runner infrastructure, runner labels, runner placement, and credential boundaries used by CI/CD workflows.
keywords: [actions, runner, ci, gitops, automation, credentials]

7.1 KiB Raw Blame History