142 lines
5.0 KiB
Markdown
142 lines
5.0 KiB
Markdown
# SCOPE
|
|
|
|
> This file helps you quickly understand what this repository is about,
|
|
> when it is relevant, and when it is not.
|
|
> It is intentionally lightweight and may be incomplete.
|
|
|
|
---
|
|
|
|
## One-liner
|
|
|
|
S4 Developer Enablement layer of the Railiance OAS Stack — owns reusable CI/CD
|
|
templates, developer portal paths, platform templates, SDKs, and buildpacks;
|
|
uses forge capabilities without owning forge runtime or runner substrate.
|
|
|
|
---
|
|
|
|
## Core Idea
|
|
|
|
Railiance is structured as independent repos per OAS Stack layer. This repo is
|
|
S4: the reusable tools and paved paths that allow the system to evolve. S4
|
|
depends on the platform (S3) being operational before tooling can use platform
|
|
services. S5 applications consume S4 templates and conventions, while
|
|
`railiance-forge` provides source hosting, registries, and runner substrate.
|
|
|
|
---
|
|
|
|
## In Scope
|
|
|
|
- Reusable CI/CD workflow templates and automation patterns
|
|
- Developer portal (self-service deployment interface)
|
|
- Platform deployment templates for workloads
|
|
- SDKs and libraries for platform consumers
|
|
- Buildpacks and image builders
|
|
- Handoff contracts to `railiance-forge` for runner labels, artifact evidence,
|
|
and registry consumption
|
|
- Template references to forge-provided runner labels and credentials documented
|
|
in `/home/worsch/railiance-forge/docs/ci-runner-actions-gitops-ownership.md`
|
|
|
|
---
|
|
|
|
## Out of Scope
|
|
|
|
- OS-level concerns → railiance-infra (S1)
|
|
- Kubernetes runtime → railiance-cluster (S2)
|
|
- Platform services → railiance-platform (S3)
|
|
- Source forge runtime, container/package registries, runner deployment,
|
|
runner labels, and runner credentials → railiance-forge
|
|
- Application deployments → railiance-apps (S5)
|
|
- App-specific workflows, release charts, and source code → app/source repos
|
|
- No re-configuration of lower layers from this repo
|
|
|
|
---
|
|
|
|
## Relevant When
|
|
|
|
- Setting up CI/CD for the Railiance stack
|
|
- Creating or modifying developer tools and deployment templates
|
|
- Defining reusable workflow templates that run on forge-provided runners
|
|
- Defining promotion conventions and evidence formats consumed by S5
|
|
- S3 is operational and tooling layer can now be built
|
|
|
|
---
|
|
|
|
## Not Relevant When
|
|
|
|
- S3 (platform services) is not yet operational (pre-condition not met)
|
|
- Infrastructure, cluster, or platform work needed (wrong layer)
|
|
- The work is Gitea/Forgejo runtime, registry endpoint, package retention,
|
|
runner deployment, or runner secret access (use `railiance-forge`)
|
|
- The work is a concrete app release or app-specific runbook (use
|
|
`railiance-apps` or the source app repo)
|
|
|
|
---
|
|
|
|
## Current State
|
|
|
|
- Status: emerging (ArgoCD deployed; no S4 workplans yet)
|
|
- Implementation: ArgoCD is deployed in the `argocd` namespace on COULOMBCORE
|
|
as a cluster addon managed from S2 for now; no S4-owned workplans yet
|
|
- Stability: n/a for S4-owned content; ArgoCD itself is operational
|
|
- Usage: ArgoCD available for GitOps deployments; formal S4 tooling work begins
|
|
after S3 baseline and should consume runner/registry capabilities from
|
|
`railiance-forge`
|
|
|
|
---
|
|
|
|
## How It Fits
|
|
|
|
- Upstream dependencies: railiance-platform (S3) must be operational
|
|
- Adjacent forge provider: railiance-forge owns source hosting, registries, and
|
|
runner substrate used by S4 workflows
|
|
- Downstream consumers: railiance-apps (S5) uses CI/CD and templates from this
|
|
layer
|
|
- Often used with: railiance-platform (S3), railiance-forge, railiance-apps (S5)
|
|
|
|
---
|
|
|
|
## Terminology
|
|
|
|
- Preferred terms: OAS Stack Level S4, developer enablement, paved path,
|
|
workflow template, promotion convention, boundary rule
|
|
- Distinguish "workflow template" from "runner substrate": templates live here;
|
|
runner deployment, labels, credentials, and health live in
|
|
`railiance-forge`.
|
|
|
|
---
|
|
|
|
## Related / Overlapping
|
|
|
|
- `railiance-platform` (S3) — pre-condition; provides services that S4 tooling depends on
|
|
- `railiance-forge` — provides source forge runtime, artifact registries, and
|
|
runner substrate consumed by S4 workflows; its runner label and GitOps
|
|
boundary contract is
|
|
`/home/worsch/railiance-forge/docs/ci-runner-actions-gitops-ownership.md`
|
|
- `railiance-apps` (S5) — consumer of S4 CI/CD and templates
|
|
|
|
---
|
|
|
|
## Provided Capabilities
|
|
|
|
```capability
|
|
type: infrastructure
|
|
title: CI/CD pipeline automation
|
|
description: Automated build, test, and deployment pipelines for Railiance workloads — planned for when railiance-platform (S3) is operational.
|
|
keywords: [ci, cd, pipeline, automation, template, build, deploy, gitops]
|
|
```
|
|
|
|
```capability
|
|
type: documentation
|
|
title: Platform deployment templates and SDKs
|
|
description: Standardised deployment templates, Helm chart patterns, SDKs, and promotion conventions enabling consistent application deployments across the Railiance stack while consuming forge-owned runners and registries.
|
|
keywords: [template, sdk, helm, deployment, developer, buildpack]
|
|
```
|
|
|
|
---
|
|
|
|
## Getting Oriented
|
|
|
|
- Start with: `CLAUDE.md` (session protocol, OAS boundary rules)
|
|
- Key files / directories: `workplans/` (empty), `Makefile`
|
|
- Pre-conditions: railiance-platform (S3) must be operational
|