GitOps on k3s: Single Repo vs Multi-Repo¶
This compares the two repo layouts covered by the hands-on guides in this section. For the background on why repo structure is a recurring GitOps debate, see GitOps: A Comprehensive Guide.
- Single repo: single-repo guide. One
gitopsrepo holds Argo CD, cluster services and every project's manifests. An earlier editable copy without the GitLab appendix is also kept as a doc: GitOps on k3s: Getting-Started Guide. - Multi-repo: multi-repo guide. A
k3s-platformrepo holds Argo CD, cluster services and a registration per project, and each project keeps its manifests in its own repo.
Both use Argo CD, Kustomize, Sealed Secrets and the same k3s handling. They differ only in where manifests live and how Argo CD finds them. Both default to GitHub and include a GitLab appendix: single-repo GitLab steps and multi-repo GitLab steps.
Recommendation¶
Use multi-repo if projects have their own source repos, different owners, or you expect the list to keep growing. That matches a cluster with several projects and more coming. Use single repo if it's just you, most apps are third-party charts, and you want the fewest moving parts. The extra cost of multi-repo is a one-time setup (credential template, registration ApplicationSets) plus one extra PR per new project.
Side by side¶
| Single repo (guide) | Multi-repo (guide) | |
|---|---|---|
| Where an app's manifests live | gitops/apps/<name>/ |
<project repo>/deploy/ |
| How Argo CD finds a project | Git directory generator: any folder under apps/ |
Git files generator: an entry in k3s-platform/projects/<name>/config.yaml |
| Onboarding a project | 1 PR: add a folder | 2 PRs: project repo deploy/, plus registration in the platform repo; and grant repo access |
| Repo credentials | 1 read-only deploy key (same on GitHub and GitLab) | 1 credential template covering all repos: GitHub App, or a GitLab group deploy token |
| Isolation between projects | One shared apps AppProject; folders aren't access-controlled |
AppProject per project: own repo only, own namespace only, no cluster-scoped objects |
| Who can deploy | Anyone with write access to the one repo can change any project | Write access to a project repo changes only that project; guardrails live in the platform repo |
| Namespaces and quotas | Created by each app (CreateNamespace=true or namespace.yaml) |
Owned by the platform repo, with ResourceQuota and LimitRange per project |
| Code + manifests in one PR | No, app code lives elsewhere | Yes, when deploy/ sits in the app's repo |
| CI image-tag write-back | App CI needs a token to push to the gitops repo | App CI pushes to its own repo with the built-in token |
| Seeing the whole cluster in Git | One git grep across everything |
Spread across repos; the platform repo lists them all |
| Cross-project changes | One PR (for example, bump an ingress annotation everywhere) | One PR per repo, or Renovate or a script |
| Renovate and CI setup | Configure once | Per repo, or via a shared preset or reusable workflow |
| Argo CD load | One repo to poll | One poll per repo; trivial at homelab scale, add webhooks for speed |
| Moving parts | Fewer | More: the registration ApplicationSet, per-project AppProjects, credential template |
| Disaster recovery | Restore the sealing key, reinstall Argo CD, apply root | Same, plus the repo credential Secret by hand, and every project repo must still exist |
Single repo¶
Pros
- Simplest to set up and to reason about: one clone, one history, one place to look.
- New project is a single folder and a single PR.
- Cross-cutting changes and refactors happen atomically in one commit.
- A deploy key and one Renovate and CI config are all you need.
- Easy to audit:
git logshows every change to the cluster in order.
Cons
- No real isolation: anyone who can merge can change any project, including infrastructure, unless you add CODEOWNERS and branch protection.
- App code and its manifests live apart, so a feature that needs a config change takes two PRs in two repos.
- App CI needs write access to the shared repo to bump image tags.
- The repo and its PR stream grow with every project; noisy history if many automated tag bumps land there.
- Splitting it later means moving folders and changing generators (doable, but a migration).
Multi-repo¶
Pros
- Each project is self-contained: code, manifests and secrets in one repo, released together.
- Strong guardrails: per-project AppProjects limit each repo to its own namespace and to namespaced resources, and quotas are set centrally.
- Fine-grained access: give someone a project repo without giving them the cluster.
- App CI updates its own
deploy/with the built-in token, with no cross-repo credentials. - Scales to many projects and people; the platform repo stays small and changes rarely.
- Removing or archiving a project is clean: drop its registration, archive its repo.
Cons
- More initial setup: a GitHub App or token, three ApplicationSets, a registration script.
- Onboarding needs two PRs plus granting Argo CD access to the new repo.
- Shared tooling (Renovate config, CI validation,
.gitignore) must be repeated or centralised via presets or reusable workflows. - Harder to see or change everything at once; cross-project changes touch many repos.
- More failure modes to understand: repo access, AppProject denials, registration typos.
Middle ground¶
You don't have to choose all-or-nothing:
- Start single, split later. Begin with the single-repo guide. When a project gets its own owner or source repo, move its folder into that repo's
deploy/and add a registration. Both ApplicationSets can run side by side in one cluster. - Third-party apps central, your own apps separate. Keep off-the-shelf software (Jellyfin, Grafana, Nextcloud) in the platform repo as you would in the single-repo guide, and give only your own code-backed apps their own repos.
On GitLab¶
If your repos are on GitLab, the comparison tilts further toward multi-repo:
- Credentials are simpler on GitLab. One group deploy token covers every project in the group, including new ones, so onboarding needs no access step. GitHub needs a GitHub App installed on each new repo, unless you install it on all repos.
- Groups map naturally. A GitLab group (with subgroups per team) is the boundary for credentials, auto-discovery, SSO and RBAC all at once.
- Shared CI is a one-liner. Each project repo
includes one validation job from the platform repo. - Some features are paid tiers on gitlab.com. Group webhooks, group and project access tokens need Premium on gitlab.com, but are free on self-managed. Workarounds are given for each: per-project webhooks, write deploy keys for CI write-back, and bot users for Renovate.
- Single repo on GitLab is equally easy: a deploy key works exactly as on GitHub. The extra cost is cross-project CI write-back, which needs a token on the gitops project stored in every app project.
| GitHub (default in both guides) | GitLab | |
|---|---|---|
| Create repos | gh repo create |
glab repo create |
| Multi-repo credential | GitHub App, installed on selected or all repos | Group deploy token (read_repository) |
| Auto-discovery | scmProvider.github (organization) |
scmProvider.gitlab (group, subgroups) |
| CI validation | GitHub Actions, reusable workflow | .gitlab-ci.yml with include |
| CI tag write-back, same repo | Built-in GITHUB_TOKEN |
Project access token or write deploy key |
| Renovate | Hosted app | Self-run scheduled pipeline |
| Webhook auth | Optional shared secret | Secret token (configs.secret.gitlabSecret) |
| SSO | Dex GitHub connector, teams | Dex GitLab connector, groups |
| Private images | GHCR | GitLab Container Registry + pull secret |
What's the same in both¶
Tool choice (Argo CD), Argo CD install and self-management, Kustomize base/overlays, Helm via Kustomize helmCharts, Sealed Secrets, k3s specifics (Traefik, HelmChart CRDs, local-path storage), the no-downtime migration technique, and day-2 operations (drift, rollbacks, image updates, notifications). Sections 1, 6, 9 and 10 of the two guides are nearly identical.