shard-wiki/research/260614-forge-wikis-deep-dive/findings.md

# git-forge wikis (Gitea · GitLab · GitHub) — deep dive (findings)

**Date:** 2026-06-14 · **Source:** SHARD-WP-0003 T5 · **Subject:** the Markdown wikis
hosted by the three major git forges — **Gitea**, **GitLab**, **GitHub** — treated as one
family because they share one architecture: *a wiki is a separate git repo of Markdown.*

## Why this dive

INTENT names **Gitea wikis** as a shard participant, and the whole project is "a **Git-based
Markdown** wiki orchestrator." The forge wikis are therefore the **least exotic, highest-
fit** backend in the entire study: the page store is *literally a git repository of Markdown
files*. After fourteen dives into DBs, CRDTs, graphs and SaaS, this one confirms the
**home case** — and sharpens it by contrasting *git-IS-the-store* (forge wikis) against
*git-is-a-mirror* (Wiki.js, UC-68).

## 1. The shared architecture — a wiki is a `.wiki.git` repo

All three forges implement a project/repo wiki as a **second, dedicated git repository**
alongside the code repo, addressable as `<repo>.wiki.git`:

- `git@host:owner/project.wiki.git` (GitLab), `…/owner/repo.wiki.git` (Gitea/GitHub).
- **Pages are Markdown files** (`Home.md`, `Some-Page.md`), one file per page; the **page
  title ↔ filename** (spaces ↔ hyphens by convention). Other markups are accepted
  (AsciiDoc, Textile, reStructuredText, Org) — GitHub/Gitea via **Gollum** (the Ruby
  git-backed wiki library), GitLab via its own renderer.
- **History is git history** — every page edit (web or pushed) is a git commit with
  author/timestamp/message. *The wiki's revision history is a real git log.*
- **Special pages** by convention: `_Sidebar`, `_Footer`, `_Header` (GitHub/Gitea),
  `_sidebar` (GitLab) — engine-rendered chrome stored as ordinary files.
- **Subdirectories / nested pages**: GitLab and Gitea support directory structure; GitHub
  wikis are historically flat (Gollum supports paths but the GitHub UI is shallow).

The decisive property: **you can `git clone` the wiki repo, edit files, commit, and push**,
and the forge UI reflects it — *and vice versa*. Git is **a** (often **the**) first-class
write path. This is exactly shard-wiki's native medium with no impedance.

## 2. Where they differ — the API matrix

| | git clone/push of `.wiki.git` | wiki content **API** | nested dirs | markups |
|--|--|--|--|--|
| **Gitea** | ✅ yes | ✅ **REST wiki endpoints** (list/get/create/edit/delete pages) | ✅ | Markdown (+Gollum-style) |
| **GitLab** | ✅ yes | ✅ **REST Wikis API** (project & group wikis) | ✅ | Markdown/AsciiDoc/RDoc/Org |
| **GitHub** | ✅ yes | ❌ **no wiki REST API** — wiki is **git-only** (Gollum) | ⚠️ flat UI | Markdown + Gollum markups |

The key asymmetry: **GitHub exposes wiki content *only* through git** (the REST/GraphQL API
covers issues/PRs/code but **not** wiki pages); **GitLab and Gitea offer both** a wiki API
*and* git access. So the **git-clone path is the universal one** (works for all three); the
API path is an *optional, capability-varying* alternative.

## 3. git-IS-the-store vs git-is-a-mirror (the UC-68 contrast)

Wiki.js (UC-68) keeps a **DB as canonical** and *maintains a git mirror* — so writing by
commit risks **racing the engine's DB↔git sync** (catalog open-Q22). Forge wikis are the
opposite: **the git repo IS the canonical store**; there is *no* separate DB of record for
wiki content. Therefore:

- **The source-of-truth question (Q22) is resolved for this case:** the `.wiki.git` repo is
  authoritative. shard-wiki can **write by commit/push directly** with no engine to race —
  the forge merely *renders* what git holds.
- The forge **API** (GitLab/Gitea), where present, is a *convenience over the same git
  repo*, not a competing store — so API-write and git-write converge on one history.

This makes forge wikis the **cleanest possible write-through file-store shard**: clone =
projection/mirror, commit = overlay-applied/write, git log = the coordination journal *as
is*.

## 4. Capability profile

| Dimension (synthesis spectrum) | Gitea / GitLab / GitHub wiki |
|--------------------------------|------------------------------|
| Attachment mode | **file-store (native: git clone)** + optional **external-API** (GitLab/Gitea wiki REST) |
| Addressing granularity | **page = file**; sub-page = path (GitLab/Gitea) |
| Content identity | path/filename within the wiki repo (title-derived) |
| Identity vs placement | placement-bound (path = identity), like a plain git repo |
| Structure | flat or directory tree of Markdown files; `_Sidebar`/`_Footer` chrome |
| History | **native git history** (real commits, authors, messages) |
| Merge model | **git** (3-way merge, branches) — though wiki repos are usually single-branch |
| Native query | none (it's files); forge full-text search over the wiki |
| Translation | **Markdown-native** (+ AsciiDoc/Org via renderer) — minimal/no translation needed |
| Attachment/write granularity | **file (page)** per commit |
| Operational envelope | ordinary git + forge; clone is cheap; API rate limits apply to API path |
| Access grant | **forge repo permissions** (delegated auth; per-repo/role ACL) |
| Content opacity | transparent Markdown in git |
| Provenance | git author/committer/timestamp per commit — native |

## 5. INTENT mapping

### Reinforcements (this is the home case)

- **Git-based Markdown orchestrator** (INTENT core): forge wikis *are* git repos of
  Markdown. The **wiki page model** (Markdown-first, path-addressed, git-versioned) maps 1:1
  — minimal adapter, maximal fit.
- **Coordination journal = git** (INTENT): the wiki repo's **git log is already the
  coordination journal** — no synthesis needed; adopt it directly.
- **Overlay before mutation**: overlays are **branches/commits** on the cloned wiki repo;
  applying = push (or open an MR/PR where the forge supports wiki MRs — GitLab does not for
  wikis, so push-to-branch + manual is the path).
- **Graceful degradation**: even GitHub (no wiki API) is fully usable via git-clone — the
  *universal* path means a limited forge is still a first-class read/write shard.
- **No silent remote mutation**: writes are explicit git pushes (or explicit API calls)
  under the user's forge credentials and repo permissions.

### Divergences (boundaries / notes — minor)

- **Capability varies by forge**: GitHub = git-only (no content API); GitLab/Gitea = git +
  API. The adapter must **model the API as an optional capability**, defaulting to the
  universal git path (T11/T14). Not a bug — exactly the capability-awareness INTENT mandates.
- **Wiki repos rarely use branches/MRs for review**: forge wikis usually edit a single
  branch directly; the rich PR-review flow is on the *code* repo, not the wiki. So
  "overlay → review → merge" needs shard-wiki to provide the review layer, not the forge.
- **Identity = path** (like any git repo) — cross-shard identity (T16) is layered above, as
  for plain git/`wiki/` subdir shards.

### What to keep

1. **git-clone as the universal, canonical file-store attach** for forge wikis — Markdown +
   git history directly as page model + coordination journal (UC-76). The reference
   easy-case backend.
2. **Forge wiki API as an optional capability** (GitLab/Gitea), with **git-only fallback**
   (GitHub) — capability-aware binding (UC-77).
3. **git-IS-store ⇒ write-by-commit is safe** (no engine race) — record this as the
   resolution of the Wiki.js mirror dilemma (Q22) for forge wikis.

## 6. UC seeds

| # | Seed | Disposition |
|---|------|-------------|
| UC-76 | Attach a **git-forge wiki** by **cloning its dedicated `.wiki.git`** — git is the native store; Markdown files = pages, git log = coordination journal; commit/push = write (no engine to race) | **new** |
| UC-77 | Attach/write a forge wiki via the **forge's wiki API** (GitLab/Gitea REST) where git-clone is unavailable or API-write is preferred; **git-only fallback** for GitHub — capability varies by forge | **new** |
| — | git-native file-store as the *canonical store* (not mirror) | enrich **UC-40** |
| — | dual-path attach (git clone vs forge API) | enrich **UC-02** |
| — | git-IS-store vs engine-maintained mirror (resolves Q22) | enrich **UC-68** |
| — | forge as an API host for the wiki resource | enrich **UC-38** |

## 7. Architecture notes for SHARD-WP-0002

- **T14 (adapter binding / attach path):** forge wikis are the canonical **file-store
  attach** — bind to the `.wiki.git` clone as the universal path; model the **wiki API as an
  optional, forge-specific capability** (present: GitLab, Gitea; absent: GitHub). One shard,
  two possible bindings converging on the same git history.
- **T11 (capability model):** "has-content-API" is a **per-forge capability flag**; git
  clone/push is the baseline every forge satisfies. Minimal adapter profile — near the
  Oddmuse-simple end but Markdown-native and git-versioned.
- **Coordination journal:** adopt the wiki repo's **git log directly** — the one backend
  where INTENT's git-backed journal needs *zero* synthesis.
- **Resolves Q22 (UC-68):** because git **is** the store (not a mirror), **write-by-commit
  is safe** — no engine DB↔git sync to race. Record the distinction *engine-mirror*
  (Wiki.js: DB canonical, careful) vs *git-canonical* (forge wikis: commit freely).

## 8. Open questions

1. For overlay → **review** → apply, does shard-wiki supply the review layer over a forge
   wiki (which lacks wiki-MRs), e.g. via a branch + its own diff/approve, or push directly?
2. When a forge offers **both** git and a wiki API (GitLab/Gitea), which does the adapter
   prefer by default — git (universal, full history) with API as a fallback for hosts where
   clone is disabled? (cf. UC-43 backend-swap under stable binding.)
3. Should the **code-repo `wiki/` subdir** shard and the **forge wiki repo** shard share one
   adapter (both git+Markdown) with a "which repo / which path" parameter, or stay distinct?

## 9. Sources

- GitLab Docs — *Wiki* (separate git repo; web/git/API; `.wiki.git`) — docs.gitlab.com
- Gitea — wiki via git clone + repository **wiki API**; forum/issue threads on
  `.wiki.git` clone (go-gitea/gitea #1426, #15420) — gitea.com / github.com/go-gitea
- GitHub — wiki = Gollum git repo (`<repo>.wiki.git`), no wiki REST API — docs.github.com
- Gollum (git-based wiki library) — github.com/gollum/gollum
- prior: `research/260614-wikijs-deep-dive/` (engine-maintained mirror contrast, UC-68)

## 10. Traceability

New UCs **UC-76–UC-77** carry the marker **⎇** in the wikiengines column of
`spec/UseCaseCatalog.md`. Enriched: UC-40, UC-02, UC-68, UC-38. Architecture cross-refs:
SHARD-WP-0002 T14, T11; coordination-journal-from-git; resolves catalog open-Q22.