railiance-apps/workplans/RAPPS-WP-0019-product-neutral-forge-object-names.md

id	type	title	domain	repo	status	flavor	owner	created	updated	related	state_hub_workstream_id
RAPPS-WP-0019	workplan	Product-neutral forge object names (forgejo-gitea-* → forge-*)	infotech	railiance-apps	finished	refactoring	railiance-apps	2026-10-21	2026-10-21	FORGE-WP-0011 CUST-WP-0071	b0cc4018-0cf3-53a3-83d6-f76d377d763a

Product-neutral forge object names

Founder decision, 2026-10-21: the legacy "gitea" terminology should leave live objects. The upstream Helm chart is called gitea, so the Forgejo objects were named forgejo-gitea* and the pods were labelled app.kubernetes.io/name: gitea. The founder also preferred the product-neutral word forge.

Scope: object names and pod labels:

• Deployment forge;
• Services forge-http and forge-ssh;
• chart Secrets forge*;
• pod label app.kubernetes.io/name: forge.

Out of scope, kept on purpose:

• the data volume gitea-shared-storage (renaming needs a data copy);
• the container names gitea/configure-gitea (hard-coded in the chart);
• the Helm release, the namespace forgejo and the host forgejo.coulomb.social. Changing these is a separate, later decision.

Leftovers from the coulombcore Gitea era (railiance-bootstrap/railiance-cluster gitea-ssh-nodeport.yaml, railiance-forge/manifests/gitea-ingress.yaml, gitea-db) are not live. They are listed for cleanup in T05.

Stage A: decouple the consumer NetworkPolicies

id: RAPPS-WP-0019-T01
status: done
priority: high
state_hub_task_id: "a6bd310d-34f5-5642-a1cb-e682a72892c9"

core-hub, issue-core and sbom-nexus allow egress to the forge by selecting app.kubernetes.io/instance: forgejo plus app.kubernetes.io/name: gitea. Drop the name label. instance=forgejo still selects only the forge server pod (the runner has no instance label), and it stays valid before and after the rename.

Diffs against live (2026-10-21) show exactly that one line per consumer:

Consumer	Source	Deploy path
core-hub	rapp-core-hub helm/core-hub/templates/networkpolicy.yaml	make deploy (Helm; the full release diff is only this line)
sbom-nexus	rapp-sbom-nexus manifests/runtime.yaml	server-side apply of the rendered sbom-nexus-runtime NetworkPolicy with field manager rapp-sbom-nexus
issue-core	rapp-issue-core manifests/30-runtime.yaml	push, pin the new revision in railiance-platform argocd/railiance01/applications/issue-core.application.yaml, manual ArgoCD sync (no other manifest change since 186c817)

Verify: each consumer still reaches http://forgejo-gitea-http.forgejo.svc:3000.

Stage B: cutover (attended, about 3 minutes of forge downtime)

id: RAPPS-WP-0019-T02
status: done
priority: high
depends_on: [RAPPS-WP-0019-T01]
state_hub_task_id: "14c47d3d-24e9-539c-ad3e-45741e1e339f"

Source: helm/forgejo-values.yaml (fullnameOverride: forge, nameOverride: forge, explicit persistence.claimName: gitea-shared-storage), manifests/forgejo-ingress.yaml (backend forge-http), manifests/forgejo-ssh-nodeport.yaml (selector forge), manifests/forgejo-compat-http-service.yaml (temporary alias).

1. Pre-check: no running Actions job. Record Helm revision 10 and Deployment revision 15.
2. kubectl -n forgejo scale deployment/forgejo-gitea --replicas=0 and wait until no forge pod is left. Helm creates the new Deployment before it deletes the old one, so this prevents two pods mounting one volume.
3. Founder: the final helm upgrade --install forgejo gitea-charts/gitea step of make forgejo-deploy, the same command as on 2026-10-21. Do not run make forgejo-deploy itself: its eso-deploy dependency would upgrade ESO.
4. Apply the Ingress, the SSH NodePort and the compatibility Service manifests.
5. Verify:
   • Deployment forge is Ready and the old forgejo-gitea* objects are gone;
   • /api/healthz returns 200;
   • git ls-remote works over HTTPS and over SSH port 30022;
   • the sign-in source is unchanged and the redirect still uses S256 PKCE;
   • core-hub, issue-core and sbom-nexus reach the forge;
   • the runner still polls.

Rollback:

1. kubectl -n forgejo scale deployment/forge --replicas=0.
2. helm rollback forgejo 10, the known-good revision from 2026-10-21. Never use revision 9.
3. Re-apply the previous Ingress and NodePort manifests from git, and delete the compatibility Service.

Stage C: consumers move to forge-http, then remove the alias

id: RAPPS-WP-0019-T03
status: done
priority: medium
depends_on: [RAPPS-WP-0019-T02]
state_hub_task_id: "e8cf80bc-3f1a-5990-b39d-4ed20cb1ba7f"

Change the in-cluster URLs forgejo-gitea-http.forgejo.svc to forge-http.forgejo.svc:

• rapp-core-hub helm/core-hub/values.yaml (forgejoBaseURL);
• rapp-issue-core manifests/10-config.yaml;
• rapp-sbom-nexus manifests/runtime.yaml.

Deploy each through its own path. When no consumer uses the old name, delete manifests/forgejo-compat-http-service.yaml and the live Service.

Tooling and docs wording

id: RAPPS-WP-0019-T04
status: done
priority: low
state_hub_task_id: "0be013cc-6bc1-5e0e-8f06-e2deef0c919c"

railiance-forge Makefile (GITEA_HTTP_SERVICE) and tools/observe_forge_resources.py (deploy/forgejo-gitea); runbooks and docs that name forgejo-gitea. Prefer "forge" wherever the concrete product is not meant.

Retire Gitea-era leftovers

id: RAPPS-WP-0019-T05
status: done
priority: low
state_hub_task_id: "169aeda8-2f4a-5bef-9343-8ad367dde71a"

Review and remove or archive the non-live Gitea-era manifests named above, once their owners confirm.

Stage A applied — 2026-10-21

Each consumer now selects the forge by app.kubernetes.io/instance: forgejo only:

• core-hub: make deploy, Helm revision 32;
• sbom-nexus: server-side apply with field manager rapp-sbom-nexus;
• issue-core: rapp-issue-core b60c194, pinned in railiance-platform 2c5d3b3, then the root app and issue-core synced manually. The root app needed a hard refresh first because ArgoCD served a cached main.

Before the change, every full render diffed against live showed only the one label line. Afterwards all three reached the forge (healthz 200).

make argocd-pin-drift in railiance-platform cannot read live Applications: its ssh hop cannot read the k3s kubeconfig. That is the same issue as RCLUSTER-WP-0020-T04.

Stage B cutover — 2026-10-21 21:24Z

The founder ran the attended cutover script. It checked the node, waited until the runner was idle, scaled forgejo-gitea to 0, waited for no running forge pod, ran the Helm upgrade, then applied the Ingress, the SSH NodePort and the compatibility Service. Results:

• Helm revision 11: Deployment forge 1/1; Services forge-http and forge-ssh; pod label app.kubernetes.io/name: forge.
• The same data volume (gitea-shared-storage) is mounted.
• The old forgejo-gitea* objects are gone, including the pod that had been in ContainerStatusUnknown for 66 days.
• Checks: API 11.0.3; HTTPS git ls-remote; SSH through the NodePort (forgejo-remote alias, fetch ok); sign-in source unchanged (ID 1 netkingdom); redirect with S256, HTTPS callback and a single scope list; core-hub, issue-core and sbom-nexus answer healthz 200 on both forgejo-gitea-http (alias) and forge-http; no runner errors.
• Downtime was about 3 minutes.

Rollback reference: scale forge to 0, then helm rollback forgejo 10, then the previous Ingress and NodePort manifests from git.

Stage C applied — 2026-10-21

In-cluster URLs now use forge-http.forgejo.svc:

• core-hub: rapp-core-hub f2a9ded, Helm revision 33; publisher rolled.
• sbom-nexus: rapp-sbom-nexus cc4db99, server-side apply; rolled.
• issue-core: rapp-issue-core 805e124 with a railiance.io/backends-revision pod annotation, so that the ConfigMap-based setting rolls the pod. Pinned in railiance-platform 51d5247, root app hard-refreshed and synced, issue-core synced: Synced/Healthy.

Each full render diffed against live first showed only the URL, plus issue-core's annotation. A cluster-wide scan afterwards found no workload or ConfigMap still naming forgejo-gitea. All three consumers answer healthz 200 on forge-http. The compatibility Service was deleted live, its manifest was removed, and HTTPS and SSH git still work.

Tooling and leftovers done — 2026-10-21

T04, tooling and docs: railiance-forge now uses FORGE_* Makefile variables, forge-status, and an observer that targets deploy/forge. Its current docs use the new object names, and docs/forgejo-on-railiance01.md was updated here.

T05, Gitea-era leftovers removed. None was referenced by a live path, and nothing named gitea runs in the cluster:

• railiance-forge FORGE-WP-0009 (finished): the stale gitea-deploy / gitea-ingress-deploy targets, which would have overwritten production with July values, plus their values files, the ingress and the old CoulombCore release values.
• railiance-platform: the gitea-db CNPG manifest and the db-deploy / db-status / db-shell / db-logs targets. They now refuse with a pointer to forgejo-db-*.
• railiance-bootstrap and railiance-cluster: helm/gitea-ssh-nodeport.yaml.
• the-custodian: the coulombcore Gitea package-push lockdown tooling.

Kept on purpose: the data volume name gitea-shared-storage, the chart-imposed container names, and the namespace, release and hostname forgejo (deferred by the founder).