Skip to content
ClearedStack

Platform · J.4 Component specifications

Plainforge specification

Design

Lightweight MIT-licensed Go Git server in the clearedstack namespace acting as cluster-primary source of truth with push-mirroring to GitHub.

J.4.42 min readLast revised November 2026

Status: Design. A specification. It describes how the component is meant to work, not something you can use on this site today. What the labels mean.

Registry entry

Holds the primary copy of every repository, announces each change and mirrors code outward.

Formerly
cs-git
Namespace
clearedstack
Repository
plainforge
Container image
lazarette.clearedstack.svc.cluster.local:5000/plainforge
Depends on
Nothing else in the platform
Depended on by
Keelworks, Shipkeeper, Moldloft, Chartroom, Bellbuoy
Boundaries
  • Git over HTTP and SSH, inside the cluster only
  • Push notifications to Keelworks
  • Outbound mirror of code to GitHub
  • Commits from Bellbuoy, Keelworks and Moldloft; reads by Shipkeeper

From the naming registry, which is the one place this component’s name is written down.

On this page
  1. Overview & Role
  2. Runtime & Resource Budget
  3. Interfaces & Data Contracts
  4. Failure Modes & Recovery
  5. Security & Clean-Room Boundaries
  6. Related pages

Plainforge (v0.1.0-draft, owned by Plainforge) is a clean-room, MIT-licensed Go Git server running in the clearedstack control-plane namespace. It replaces heavy third-party forges such as Forgejo—eliminating 40+ database tables and hundreds of megabytes of RAM—while serving as the cluster's primary source of truth for code and configuration.

Overview & Role#

ClearedStack treats the cluster as primary and GitHub as the public mirror:

  • Headless Primary Git Server: Hosts bare .git repositories for clearedstack.com, all 10 deterministic workers (Trawl through Bellbuoy), sub-tools, and app.yaml deployment manifests.
  • Webhook & Mirror Trigger: Whenever a commit lands on main or a new tag is created, Plainforge fires a push webhook to Keelworks and push-mirrors source commits and tags to GitHub.
  • Zero Web UI / Account Overhead: Public browsing, status inspection, and anonymous ✎ Edit proposals happen in Conn, so Plainforge needs no user accounts, issue UI, or PR web frontend.

Runtime & Resource Budget#

AttributeValue
Namespaceclearedstack (Control Plane)
Kindcontrol-plane
Versionv0.1.0-draft
Owning RepoPlainforge (plainforge)
RAM Request64 MiB
Priority ClassHigh (Control Plane — protected from eviction)
StoragePersistent Volume Claim (bare .git repositories; 1 of 3 cluster PVCs)
Network ExposureCluster-private (ClusterIP only); outbound HTTPS push-mirror to GitHub

Interfaces & Data Contracts#

Peer / TargetDirectionProtocol / MechanismData Contract
BellbuoyInboundCluster-private Git / Patch APICommits approved public edits (from Countersign) and opens fingerprinted needs_subtool tasks in owning repos
KeelworksOutbound / InboundPush webhook + Git commitReceives push webhooks on main/tag updates to start builds; commits updated app.yaml image digests tagged [skip-ci]
ShipkeeperInboundCluster-private Git readWatches app.yaml manifests in Plainforge to reconcile deployments via Server-Side Apply
GitHubOutboundHTTPS Git push-mirrorMirrors source commits and tags on change; zero container images are ever pushed to GitHub

Failure Modes & Recovery#

  • GitHub Unreachable / Rate-Limited: Because Plainforge is primary, internal commits, Keelworks builds, and Shipkeeper deployments continue operating normally even if outbound mirroring to GitHub is temporarily unreachable.
  • Build Loop Prevention: Digest updates written back by Keelworks to app.yaml are tagged [skip-ci] so Plainforge does not re-trigger an infinite build loop.
  • Volume Loss / Corruption: Plainforge holds one of the cluster's three Persistent Volume Claims. Nightly backups archive the bare repositories, encrypt them client-side with age, and transfer them off-node. The automated monthly restore drill mounts the restored bare repositories in an isolated scratch area and runs Git consistency checks to prove recoverability.
  • Pod Restart: High Priority Class protects Plainforge from eviction; on restart, k3s reattaches the PVC with all bare repositories intact.

Security & Clean-Room Boundaries#

  • ClusterIP Only: Plainforge has zero public Ingress and is unreachable from the open internet. Default-deny NetworkPolicy restricts cluster-internal access to authorized control-plane peers.
  • No Unapproved Public Commits: Anonymous ✎ Edit proposals cannot reach Plainforge directly; they must pass the 5-layer anti-spam shield in Muster and explicit human approval in Countersign before Bellbuoy writes a commit.
  • Source-Only Public Mirror: Only source code commits and tags mirror to GitHub; signed OCI container images remain strictly internal inside Lazarette.
  • Clean-Room MIT Licensing: Written from scratch in Go under the MIT license, with no upstream forge license or dependency baggage.
  • Unprivileged Execution: Runs as non-root with dropped Linux capabilities and no privilege escalation.

Found a mistake, or something that has gone out of date? Open an issue or write to [email protected]. This page is a text file you can read and correct: Source of this page.