# 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.