From d99c2d989486e6b3b3c0b6b19217672a8ce791b5 Mon Sep 17 00:00:00 2001 From: matamune Date: Tue, 12 May 2026 23:20:42 +0000 Subject: [PATCH] Track Forgejo fork problem space notes --- forgejo-forking-problem-space.md | 255 +++++++++++++++++++++++++++++++ 1 file changed, 255 insertions(+) create mode 100644 forgejo-forking-problem-space.md diff --git a/forgejo-forking-problem-space.md b/forgejo-forking-problem-space.md new file mode 100644 index 0000000..53642e7 --- /dev/null +++ b/forgejo-forking-problem-space.md @@ -0,0 +1,255 @@ +# Forgejo Forking Problem Space + +Date: 2026-05-12 + +## Current Setup + +Created a jojo.build mirror: + +- Repo: https://jojo.build/peezy-tech/jojo +- SSH: `ssh://git@jojo.build/peezy-tech/jojo.git` +- Upstream: `https://codeberg.org/forgejo/forgejo.git` +- Default branch: `forgejo` +- Mirror interval: `8h` + +This is currently a mirror, not a working fork branch. That is a good starting +point for source inspection and tracking upstream movement. It is not yet a good +place for custom patches, because mirror updates are expected to follow upstream. + +## Executive Summary + +Forking Forgejo is feasible, but it is not a small maintenance commitment. +Forgejo is a full Go web application with a substantial frontend build, +database migrations, templates, Actions integration, SSH/HTTP Git serving, +packages, OAuth2, and admin surfaces. A fork is reasonable only if the desired +customization cannot be achieved through supported configuration, OIDC, reverse +proxy auth, static assets, or template overrides. + +For SIWE specifically, the preferred order remains: + +1. Use SIWE through an external OpenID Connect provider. +2. Use a trusted reverse proxy that performs SIWE and passes identity headers. +3. Fork Forgejo only if we need first-class SIWE UX or native account semantics. + +## Upstream Release Cadence + +Forgejo stable releases are published quarterly. LTS releases are published in +the first quarter of each year and receive critical bugfix/security support for +one year and three months. The current LTS line is v15.0, released 2026-04-16 +and supported until 2027-07-15. + +Implication: a fork has to either: + +- Track every quarterly release and absorb breaking changes often. +- Track only LTS releases and accept slower access to new Forgejo features. +- Track upstream `forgejo` continuously, which maximizes merge churn. + +For a production instance, an LTS-based fork is the most conservative option. + +## What A Fork Would Own + +At minimum, a maintained fork owns: + +- A source branch policy. +- CI for Go, frontend, templates, linting, and tests. +- Binary or container image builds. +- A release/version naming scheme. +- Security patch intake. +- Upgrade rehearsals against jojo.build data. +- Documentation for local patches. +- A rollback path to upstream Forgejo. + +The risky areas are not only code conflicts. They are also database migrations, +template changes, auth/session behavior, Actions behavior, and generated assets. + +## Build And Test Surface + +Forgejo source includes: + +- `go.mod` for the backend. +- `package.json` and `webpack.config.js` for frontend assets. +- `Makefile` for build/test targets. +- `Dockerfile` and `Dockerfile.rootless`. +- Published release notes in `release-notes-published/`. + +Official build docs require Go, Node.js/npm, and `make`. Older docs mention Go +1.22+ and Node 20+, but we should verify exact versions from the branch we pin +before building production artifacts. + +Initial local validation target should be: + +```bash +make help +make deps-frontend +make frontend +make test +make build +``` + +Exact target names need confirmation from the current Makefile before scripting. + +## Auth Extension Surface + +Forgejo has configurable auth sources: + +- Local database auth. +- LDAP via BindDN. +- LDAP simple auth. +- SMTP. +- PAM. +- OAuth2. +- OpenID Connect. +- OpenID. +- Reverse proxy header auth. + +From source inspection, auth source types are compiled into the application. +OAuth2 providers are registered in Go during init via an internal Goth provider +registry. That registry is useful for patching Forgejo, but it is not an +external plugin API. + +Native SIWE would likely require one of these approaches: + +- Add a first-class OAuth2/OIDC provider if SIWE is presented as OIDC. +- Add a custom auth flow and routes for EIP-4361 challenge/signature handling. +- Add account-linking fields for wallet addresses and ENS-derived display data. +- Add admin settings and migration(s) if wallet addresses become persisted + first-class identities. + +The more native the SIWE behavior, the more the fork touches security-critical +surface: sessions, CSRF, account linking, auto-registration, 2FA bypass rules, +and recovery flows. + +## SIWE Fork Design Questions + +Before writing code, resolve these: + +- Is an Ethereum address the canonical Forgejo username, an external account + identifier, or merely a linked credential? +- Do users need email addresses? +- Can a wallet create a new Forgejo account automatically? +- How are lost wallets handled? +- Can one Forgejo account link multiple wallets? +- Is ENS only display metadata, or does it influence identity? +- Are smart-contract wallets/EIP-1271 required? +- Which chains are accepted? +- Does SIWE bypass local 2FA, complement it, or become a second factor? +- How do Git over HTTPS, SSH keys, access tokens, and API auth map to wallet + sign-in? + +These questions matter more than the login button. Forgejo identity is used by +Git, issues, packages, Actions, API tokens, and admin permissions. + +## Fork Strategies + +### Strategy A: No Fork + +Use config, OIDC, reverse proxy auth, and supported UI customization. + +Best for: + +- Branding. +- Trusted SIWE/OIDC experiment. +- Avoiding security patch ownership. + +Risk: + +- Less native UX. +- Identity model constrained by Forgejo's existing auth flows. + +### Strategy B: Patch Branch On LTS + +Create a branch like `jojo/v15.0` from the current LTS tag, maintain a minimal +patch stack, and periodically rebase or merge v15.0 patch releases. + +Best for: + +- Production stability. +- Small, well-contained changes. +- Predictable security patch intake. + +Risk: + +- Larger jumps when moving to the next LTS. +- Backport work if desired features land in newer stable releases. + +### Strategy C: Patch Branch On Upstream `forgejo` + +Maintain `jojo/forgejo` on top of upstream development. + +Best for: + +- Contributing changes upstream. +- Early access to Forgejo improvements. + +Risk: + +- Highest churn. +- Bad fit for production unless we have strong CI and staging. + +### Strategy D: Hard Product Fork + +Rename/rebrand deeply, ship independent releases, and diverge freely. + +Best for: + +- Building a distinct forge product. + +Risk: + +- Largest maintenance burden. +- Security, release, migration, and support responsibilities become ours. + +This should be avoided unless jojo.build becomes a product-level Forgejo +distribution. + +## Recommended Path + +Use the mirror as the upstream intake point. Do not customize the mirror branch. + +Next create a working fork branch only when we have a concrete patch to test: + +- `jojo/v15.0` from the latest v15.0.x tag for production-minded patches. +- `jojo/forgejo` from upstream `forgejo` for exploratory upstreamable patches. + +For SIWE, first prototype without a Forgejo fork: + +1. Configure a SIWE OIDC provider against a test Forgejo instance. +2. Test user creation, account linking, logout, API tokens, Git over HTTPS, and + SSH key management. +3. Separately test reverse proxy header auth with a toy trusted auth service. +4. Only fork if those approaches fail on essential UX or identity semantics. + +## Maintenance Checklist For Any Fork + +- Track upstream release notes and security announcements. +- Keep a patch inventory with rationale and owner. +- Rebase/merge upstream into a staging branch first. +- Run full build and test suite. +- Run upgrade rehearsal against a copy of production data. +- Smoke test login, repo browsing, Git SSH, Git HTTPS, Actions, packages, + mirrors, and admin pages. +- Keep a rollback artifact for the previous known-good binary/container. +- Document every app.ini setting required by the fork. + +## Open Questions + +- Is jojo.build currently installed from binary, container, package manager, or + local build? +- How is production deployment currently rolled out and rolled back? +- Do we want custom patches to be private indefinitely, or upstreamable? +- Would SIWE be required for all users, optional, or only for selected orgs? +- Is the target experience "login with wallet" or broader onchain identity? +- Are we willing to run an external IdP such as a SIWE OIDC provider? + +## Sources Consulted + +- Forgejo mirror created from `https://codeberg.org/forgejo/forgejo.git`. +- Forgejo auth docs: https://forgejo.org/docs/v11.0/user/authentication/ +- Forgejo OAuth2 provider docs: https://forgejo.org/docs/v13.0/user/oauth2-provider/ +- Forgejo customization docs: https://forgejo.org/docs/next/admin/advanced/customization/ +- Forgejo config cheat sheet: https://forgejo.org/docs/latest/admin/config-cheat-sheet/ +- Forgejo upgrade guide: https://forgejo.org/docs/next/admin/upgrade/ +- Forgejo release schedule: https://forgejo.org/docs/v11.0/admin/release-schedule +- Forgejo compile-from-source docs: https://forgejo.org/docs/v7.0/developer/from-source/ +- SIWE docs: https://docs.siwe.xyz/ +- SIWE hosted OIDC docs: https://docs.login.xyz/servers/oidc-provider/hosted-oidc-provider