Andrew Mercer
on this page

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 gitops repo 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-platform repo 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 log shows 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.