GitHop/docs/adr/0001-gitea-as-forge-foundation.md

ADR 0001: Use Gitea as the forge foundation

• Status: Accepted
• Date: 2026-07-11

Context

HopWeb needs reliable Git hosting, repository permissions, users and organizations, review primitives, webhooks, CI integration, packages, releases, and administration. Rebuilding this foundation would delay the Hop-native workflow and create a large security and maintenance burden.

Gitea is a mature, MIT-licensed, Go-based forge with a REST API, OAuth2 provider, webhooks, Git LFS, package registries, and a production-capable Actions system. It supports custom assets, themes, templates, and repository tabs, which are enough to prototype a unified Hop experience without immediately carrying a large source fork.

Decision

Use a pinned upstream Gitea release as the forge substrate. Build Hop as a separate control-plane service and Hop-native web experience that integrates with Gitea through stable APIs, webhooks, OAuth, and Git protocols.

Adopt a staged customization policy:

1. configuration, branding, templates, assets, and API integration;
2. small upstreamable extension points where integration seams are missing;
3. a shallow maintained fork only for essential Hop-native behavior.

Hop domain data will live outside the Gitea schema. Cross-service operations will use stable IDs, idempotency keys, and explicit reconciliation rather than distributed database writes.

Consequences

Positive

• The team can focus on Hop's state model and collaboration experience.
• Standard Git clients and familiar forge features work from the beginning.
• Gitea security fixes and features can be consumed from upstream.
• A separable control plane makes the Hop model portable to another Git host.

Costs and risks

• A visually unified product must compose two service boundaries.
• Some acceptance operations need careful compensation and reconciliation.
• Template overrides are version-sensitive.
• A deep fork would make upstream upgrades expensive.
• Public multi-tenant runners require a stronger isolation model than Gitea's default trusted-runner assumptions.

Guardrails

• Pin exact Gitea versions and test upgrades in automation.
• Keep a patch ledger for every source-level deviation from upstream.
• Never edit vendored Gitea code for branding alone.
• Prefer contributing generic extension points upstream.
• Keep the Hop control plane independently testable and deployable.
• Threat-model Git hooks, webhooks, runner registration, job tokens, and untrusted repository content before supporting public execution.

Revisit when

• Gitea's architecture prevents a core Hop invariant;
• the source patch set grows beyond a routinely rebaseable size;
• transactional acceptance cannot be made reliable across the boundary; or
• operating two services costs more than owning a cohesive fork.