Hop
dd2c0abfd2
Hop-State: A_06FN3NFQ6P95HFKCSC22JMR Hop-Proposal: R_06FN3NF43ARPM6SBXX0F15R Hop-Task: T_06FN3MVGY3MT82ESQ89BND0 Hop-Attempt: AT_06FN3MVGY092BFA5MR9C7EG
70 lines
2.8 KiB
Markdown
70 lines
2.8 KiB
Markdown
# 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.
|
|
|