railiance-apps/workplans/RAPPS-WP-0016-forgejo-netkingdom-login.md

id	type	title	domain	repo	status	flavor	owner	topic_slug	created	updated	depends_on	related_repos
RAPPS-WP-0016	workplan	Forgejo sign-in through NetKingdom, before the forge closes	infotech	railiance-apps	ready	implementation	claude-code	railiance	2026-10-08	2026-10-08	KEY-WP-0038	prj-forgejo-org-refactor key-cape railiance-platform

RAPPS-WP-0016 - Forgejo sign-in through NetKingdom, before the forge closes

Why

forgejo.coulomb.social is closing: private by default, no anonymous access (prj-forgejo-org-refactor ORGREF-WP-0002, decision decisions/forge-visibility-policy.md). The founder's condition is that sign-in runs through NetKingdom first. railiance-apps owns the Forgejo Helm release (docs/forgejo-on-railiance01.md: S5 Helm release, ingress, operator Makefile), so the Forgejo side lands here. This plan is ORGREF-WP-0002-T05. The NetKingdom side is key-cape KEY-WP-0038.

Boundaries

• Founder guardrail: tighten gradually; never lock anyone out; never risk assets; never reach a state that is hard to repair. Every step keeps the current sign-in path working until the new one is proven.
• No visibility change in this plan. Repositories, packages and REQUIRE_SIGNIN_VIEW are ORGREF-WP-0002-T08.
• Configuration in git. The authentication source is declared in helm/forgejo-values.yaml (gitea.oauth), with its secret drawn from an ExternalSecret over OpenBao. No click-ops, and no secret value in git.
• Open registration is already disabled (service.DISABLE_REGISTRATION: true). This plan keeps it that way.

Tasks

id: RAPPS-WP-0016-T01
status: todo
priority: high

T01 — Make the local administrator a sealed break-glass

Before anything about sign-in changes: confirm the local administrator account works, keep its credential only in OpenBao, and document recovery (who, how, where it is logged) in docs/forgejo-on-railiance01.md. Verify one break-glass sign-in and record it without the credential.

Acceptance: a recorded break-glass sign-in, with the recovery path written down. This is the "never lock ourselves out" floor for every later step.

id: RAPPS-WP-0016-T02
status: wait
depends_on: [RAPPS-WP-0016-T01, KEY-WP-0038-T02]
blocking_reason: "Needs break-glass in place and the NetKingdom client registered with its secret in custody."
priority: high

T02 — Add the NetKingdom authentication source

• an ExternalSecret delivering the forgejo client secret from OpenBao (path from KEY-WP-0038-T02) to a Secret in the forgejo namespace
• gitea.oauth: name netkingdom (must match the redirect URI registered in key-cape), provider openidConnect, auto-discovery from https://kc.coulomb.social/.well-known/openid-configuration, scopes openid profile email groups, group-claim name groups
• oauth2_client settings: no automatic account creation for unknown subjects; account linking to existing local accounts by username after a successful local sign-in (so the founder and agent accounts keep their history)
• Helm upgrade with the previous revision noted for rollback

Local password sign-in stays enabled.

Acceptance: the "Sign in with netkingdom" option appears. Local sign-in still works. Rollback is one helm rollback to the noted revision.

id: RAPPS-WP-0016-T03
status: wait
depends_on: [RAPPS-WP-0016-T02]
blocking_reason: "Linking and team mapping follow a working authentication source."
priority: high

T03 — Link accounts and map groups to teams

• The founder links their account through NetKingdom (MFA), then signs in again through NetKingdom only and sees the same repositories, organisations and admin rights.
• Map NetKingdom groups (names agreed in KEY-WP-0038-T01) to organisation teams: owners and readers at least. Create the read-only teams that ORGREF-WP-0002-T06 consumers will use.
• Apply KEY-WP-0038-T03's decision on agents and services: NetKingdom sign-in, or scoped tokens bound to service identities.

Acceptance: founder and one agent work through NetKingdom; group-to-team mapping verified by adding and removing one test membership; break-glass still works.

id: RAPPS-WP-0016-T04
status: wait
depends_on: [RAPPS-WP-0016-T03]
needs_human: true
blocking_reason: "Restricting local password sign-in is a founder decision once NetKingdom sign-in is proven."
priority: medium

T04 — Decide on local password sign-in

Once NetKingdom sign-in has been used for a while without problems, the founder decides whether local password sign-in is turned off for everyone except break-glass. This is not required to close the forge; it is the next tightening step, taken separately.

Also in scope: stale node credential

The k3s registries.yaml on railiance01 still holds a login for the frozen Gitea host 92.205.130.254 (ORGREF-WP-0002-T02). Coordinate its removal with the node owner when ORGREF-WP-0002-T06 adds the forge registry login, in the same change.