# SCOPE This file defines what `railiance-forge` owns, when to use it, and where its boundaries stop. Last reviewed: 2026-06-13 --- ## 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: 1. lower layers provide servers, Kubernetes runtime, databases, storage, and secret custody; 2. this repo owns the source forge runtime and artifact publication surface; 3. `railiance-enablement` owns reusable CI/CD templates and developer paved paths; 4. `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. The runner, Actions, and GitOps ownership contract lives in `docs/ci-runner-actions-gitops-ownership.md`. The backup, restore, and secret custody handoff contract lives in `docs/backup-restore-secret-handoff.md`. The observability and operating evidence contract lives in `docs/observability-operating-evidence.md`. The Fabric graph declarations for forge capabilities and edges live in `/home/worsch/railiance-fabric/fabric/`. --- ## 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 now live-facing; forge owns the reviewed public Gitea HTTPS ingress for the web UI, package registry, and OCI registry. Raw node IP HTTP access is not part of the supported forge surface. - 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, public HTTPS 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. --- ## Related / Overlapping - `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 1. Read `AGENTS.md` for session protocol and State Hub conventions. 2. Read `INTENT.md` for stable purpose. 3. Read this file for scope and boundaries. 4. Read active files in `workplans/`. 5. For registry operations, read `docs/gitea-container-registry.md` and `docs/gitea-package-registry.md`. 6. For runner, Actions, and GitOps ownership, read `docs/ci-runner-actions-gitops-ownership.md`. 7. For backup, restore, and secret custody handoffs, read `docs/backup-restore-secret-handoff.md`. 8. For observability and release-readiness evidence, read `docs/observability-operating-evidence.md`. 9. For Fabric graph declarations, read `/home/worsch/railiance-fabric/fabric/` and query them with `railiance-fabric`. 10. For migration context, read `/home/worsch/railiance-apps/workplans/RAILIANCE-WP-0006-railiance-forge-extraction.md`. --- ## Provided Capabilities ```capability 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] ``` ```capability 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] ``` ```capability 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] ```