generated from coulomb/repo-seed
tegwick
9c4b400cb6
All checks were successful
Forge Runner Smoke / compatibility-smoke (push) Successful in 0s
222 lines
8.1 KiB
Markdown
222 lines
8.1 KiB
Markdown
# 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]
|
|
```
|