Skip to content

ADR-0003: Forgejo for code hosting only — issue tracking stays as markdown files

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

Context

We added Forgejo (git.fmm.house) to self-host git. Forgejo ships a full issues + projects tracker, but this repo already has an established issue/PRD workflow: issues live as markdown files under .scratch/<feature>/, driven by the /wayfinder → /to-tickets → /to-spec → /implement → /code-review skills (see AGENTS.md, docs/agents/issue-tracker.md). Two issue surfaces would fragment the source of truth.

Decision

Run Forgejo for code hosting only. Disable issue tracking at the instance level via FORGEJO__repository__DISABLED_REPO_UNITS = repo.issues, repo.ext_issues, repo.projects. Issue/PRD tracking remains the markdown-file workflow. Pull requests (repo.pulls) stay enabled.

Lock the instance down for its public-facing URL: registration disabled, sign-in required to view. Git-over-SSH on host port 2222; SQLite storage (single user, no separate Postgres).

Consequences

  • One source of truth for issues (markdown files); no unused/parallel tracker to keep tidy.
  • Code review of the working tree stays on /code-review; Forgejo PRs are available if we ever want cross-branch review, but aren't the primary flow.
  • Admin account is bootstrapped via forgejo admin user create (registration is off).
  • Setup captured in stacks/forgejo/compose.yml; see the Stacks table in CONTEXT.md.