Keep the homelab in a monorepo

Context

The homelab uses several infrastructure tools that share documentation, secret handling, and operating procedures. One person operates it, so the forge, the backups, and the change flow must cost little to run.

Decision

Keep Ansible, Terraform, Kubernetes manifests, scripts, and documentation in one repository.

Host the repository on GitHub Free as a private repository. Do not mirror it to other forges. GitLab.com Free is the fallback forge. Gitea is retired.

Back up every repository from the Docker host to a TrueNAS NFS dataset. A daily systemd timer updates a bare repository and keeps dated bundles (30 daily, 12 monthly), and the existing TrueNAS to B2 job copies them offsite. The Docker host serves the homelab mirror over read-only SSH, so Flux can reconcile from it during a GitHub outage. TrueNAS runs no custom code. Losing the site and the GitHub account together is accepted.

Use this repository as the Flux source for staging and production. Both clusters sync main, each from its own directory: kubernetes/clusters/staging and kubernetes/clusters/prod. A change reaches staging first and production later, through a change to each directory. Chart versions, image tags, and values that change behavior live in those directories, so no shared base changes both clusters at once.

Agents and Renovate work as the private GitHub App igresc-homelab. If the owner buys GitHub Pro, every change to main goes through a pull request with required checks, and CODEOWNERS requires the owner's approval for the paths that control the process. Free has no protected branches, required checks, or CODEOWNERS on private repositories, so without Pro changes go straight to main as they do today. ADR 011: Change flow and promotion holds the details.

The repository must contain no plaintext secrets. Before any repository leaves the LAN, run gitleaks over its full history and fix or rewrite what it finds.

Keep all documentation as Markdown in the repository. Build a curated public site with Zensical. An allowlist selects its pages. The site is a portfolio, so it holds most docs: ADRs, platform and architecture pages, the hardware overview, runbooks, and service guides. Pages with personal data, third-party details, or unfixed security weaknesses stay private. A CI check fails if the built site contains a page outside the allowlist. CI builds the site into the homelab-docs image on GHCR. The container runs on staging Talos, later production, behind the public ingress at docs.dev.igresc.com. GitHub Pages is not used.

Implementation status

The repository is still on Gitea. The Talos staging cluster syncs main from kubernetes/clusters/staging. Production is still k3s and syncs from the separate igresc/gitops repository. The GitHub move, the Docker host Git backup, the igresc-homelab App, the Pro decision, and the public site are future work.

Consequences

All changes are visible in one place. Clear repository conventions must keep each tool in its intended role.

A bad commit can affect more than one environment. Environment directories, the staging soak, and required checks if Pro is bought (ADR 011) reduce that risk.

A private repository on a hosted forge removes the exposure of public mirrors and the work of keeping them in sync. Recovery during a GitHub outage depends on the Docker host and its NFS-backed TrueNAS copy instead.

Pages left out of the Zensical navigation still appear in the HTML, the search index, and the sitemap. For this reason, the site build uses an allowlist and not the whole docs tree.

Rollout gates

• gitleaks passes over the full history of every repository before any of them leaves the LAN. open
• If the owner bought Pro, branch protection blocks direct pushes to main, and CODEOWNERS works. open
• Both clusters reconcile from GitHub with read-only deploy keys. open
• The Docker host Git backup runs daily, and one bundle restore has passed. open
• One Flux reconcile from the Docker host's NFS-backed copy has passed with GitHub blocked. open
• The public site builds from its allowlist into the homelab-docs image, its CI check passes, and it serves at docs.dev.igresc.com. open

docs/decisions/001-monorepo.md