7.3 KiB
Git-first project documentation
The project's git_repository_url is the only repository configuration on a Project. Markdown under docs/**/*.md, plus root README.md and AGENTS.md, is authoritative in Git. The dashboard keeps a read-only SQLite index for the Documentation page and MCP; it never edits or pushes Markdown.
Setup for self-hosted Gitea
- Set each project's existing HTTPS Git repository URL. The Git server must advertise a default branch through
HEADand be reachable by the Django and MCP processes. - Set
PROJECT_DOCS_ALLOWED_GIT_HOSTSto an explicit comma-separated host/port allowlist. The default isgit.jorendegraaf.eu. Repository URLs with credentials, query strings, fragments, percent escapes, non-HTTPS schemes, or path traversal are rejected for syncing. Configure DNS/network access separately; a URL field alone does not grant access. - For private repositories, create a dedicated Gitea credential with read-only repository contents permission for each project. Gitea documents the
read:repositorytoken scope; verify that your instance also accepts the token for Git-over-HTTPS fetch. Store the mapping outside Git in the Django/MCP service environment asPROJECT_DOCS_CREDENTIALS_JSON, e.g.{"<project-uuid>":{"repository_url":"https://git.jorendegraaf.eu/owner/repo.git","username":"readonly-user","token":"<secret>"}}. The repository URL must match the project's configured URL exactly, binding that credential to one endpoint. Use a different credential per project. Protect the environment file, rotate tokens through Gitea, and restart both services after changes. No token is sent to the browser or returned by MCP. - Set
PROJECT_DOCS_MIRROR_ROOTto a persistent, private directory outside any web/static alias, writable only by the app account. Its default is underPROJECTS_PRIVATE_MEDIA_ROOT/git-docs. Back up the database and mirror if historical reads are important. The current index can be rebuilt from Git; the shallow mirror holds only recent history. - Run migrations and restart Django and MCP. Open the project's Documentation link. An authorized read checks for a refresh when the configured interval has elapsed; an editor can use Refresh from Git. The default interval is 900 seconds. A manual refresh is limited to one attempt per 30 seconds. There is no cron, timer, worker queue, or webhook in this version, so an idle project is refreshed on its next authorized read.
The fetch uses a private bare mirror, no working tree, no submodule checkout, no hooks, no scripts and no frontend build. It fetches the advertised default branch with depth 50, reuses the mirror for incremental fetches, and indexes only regular UTF-8 Markdown files in the approved paths. Limits default to 100 MiB per mirror, 5 MiB tree listing, 10 MiB total Markdown, 1 MiB per file and 500 files. Configure PROJECT_DOCS_MAX_MIRROR_BYTES, PROJECT_DOCS_MAX_TREE_BYTES, PROJECT_DOCS_MAX_CONTENT_BYTES, PROJECT_DOCS_MAX_FILE_BYTES, and PROJECT_DOCS_MAX_FILES if needed. The host needs Git and the Linux prlimit utility; Git commands have time, CPU and file-size limits. Redirects are disabled. A failed fetch/index leaves the last good database index intact and displays an error.
What freshness means
The UI and MCP distinguish the indexed commit, last successful fetch/index, most recently observed remote HEAD, and the documentation accuracy audit. A successful fetch proves the index matches the fetched Git commit; it does not prove Markdown claims still match code. A failed fetch preserves old content with a stale/error label. When the repo URL changes, the previous index remains visible but is marked stale until the new repository successfully indexes.
The root docs/.audit-state.json is a Codex workflow record in Git, not the sync state. Its required fields are schema_version, last_successful_audit (UTC ISO timestamp), audit_interval_days, and last_audited_commit (full SHA). The dashboard reads it at the indexed commit and reports Unknown/Due when missing or invalid; it reports a commit mismatch when code has changed since the audit. Codex checks it at the start of card work. A user can manually request “audit docs now” to override the interval. The audit is bounded and opportunistic, never a cron or systemd job. Failed or partial audits record last_attempt and last_status without advancing the last successful audit.
Run python scripts/docs_audit.py for a deterministic due/change/relative-link preflight, or python scripts/docs_audit.py --force for a manual override. It never edits state or declares semantic accuracy; Codex reviews relevant code and writes a report before advancing success fields. The initial baseline report is docs/audits/2026-10-20.md. Historical ZIP/wiki research under docs/research/ is superseded for implementation.
UI and MCP
The Documentation page provides folder navigation, a sanitized Markdown view, search, source links, raw Markdown, and recent Git history for the current path. Relative Markdown links to indexed documents are rewritten to project-scoped routes; missing targets lose their link. Images and raw HTML are not rendered. Historical reads are limited to the retained shallow mirror and the same path; renamed and deleted files are not browsable in this version.
Read-only MCP tools are docs_list, docs_search, docs_read, docs_history, and docs_diff. They use existing projects:read authorization and project membership. Search results return short snippets; reads return at most 250 lines or 30,000 characters with a continuation cue. Revisions must be retained commits for the requested path. MCP never returns Git credentials and does not accept arbitrary repository URLs or local filesystem paths. Codex working directly in a local checkout should read docs/ there; remote clients use MCP.
docs_sync(project, expected_remote_commit?) lets a client with projects:write scope and project edit access request the same bounded refresh as the authenticated UI button. It returns completed, already_current, in_progress, or failed with the observed remote and indexed commits, document count, timestamps, safe error, and cooldown hint. expected_remote_commit must be a full Git hash; a different observed remote commit is reported as a failed expectation even if the new index was committed. Calls within the 30-second manual cooldown do not fetch again. A successful index refresh does not advance the separate documentation accuracy audit. After completed, clients can call docs_list or docs_read for the returned indexed commit.
Recovery and rollback
If fetches fail, check the configured host allowlist, the repository's default branch and access, private credential scope, and mirror permissions. The last good index remains available. A subsequent successful refresh atomically replaces it, including deletions. To rebuild a corrupted mirror, stop both services, move only that project's UUID-named mirror directory aside, then refresh. Keep its old directory until the new index is verified if historical reads matter. Deleting a project removes its mirror after the database transaction commits. Database migrations and the previous application version are the application rollback path; preserve a database backup before rolling back schema changes. No documentation changes are pushed by the web app.