Skip to main content

Repository Strategy

Two-Tier Layout​

github.com/myorg/
│
├── platform-gitops/              ← owned by platform team
│   ├── argocd/                   ← AppProjects + ApplicationSets (all domains)
│   ├── crossplane/               ← Providers + XRDs + Compositions
│   ├── k8s/platform/             ← Platform service manifests
│   ├── k8s/rbac/                 ← Group and User RBAC bindings
│   └── backstage-templates/      ← All Scaffolder templates
│
├── payments-gitops/              ← owned by payments team
│   ├── k8s/                      ← App manifests (all envs)
│   ├── crossplane/claims/        ← Crossplane Claims (all envs)
│   └── catalog/                  ← Backstage entities for this domain
│
└── orders-gitops/                ← owned by orders team
    ├── k8s/
    ├── crossplane/claims/
    └── catalog/

Responsibility Split​

WhatWhereWho
AppProjectsplatform-gitops/argocd/projects/Platform team
ApplicationSetsplatform-gitops/argocd/applicationsets/Platform team
Crossplane Providers / XRDs / Compositionsplatform-gitops/crossplane/Platform team
Platform service manifestsplatform-gitops/k8s/platform/Platform team
RBAC manifests (groups + users)platform-gitops/k8s/rbac/Platform team
Backstage templatesplatform-gitops/backstage-templates/Platform team
App manifests (all envs){domain}-gitops/k8s/Domain team
Crossplane Claims{domain}-gitops/crossplane/claims/Domain team
Backstage catalog entities{domain}-gitops/catalog/Domain team

The Key Rule​

Platform-gitops controls where and how things are deployed.
{domain}-gitops controls what is deployed.
Domain teams never write ArgoCD config or Crossplane Compositions.
Platform team never writes domain manifests or Claims.

ApplicationSet — Central Repo, Domain Source​

# platform-gitops/argocd/applicationsets/payments-gateway.yaml
spec:
  generators:
    - matrix:
        generators:
          - list:
              elements:
                - service: api
                - service: worker
          - clusters:
              selector:
                matchExpressions:
                  - key: env
                    operator: In
                    values: [dev, staging, prod]
  template:
    spec:
      source:
        repoURL: https://github.com/myorg/payments-gitops  # ← domain repo
        path: k8s/{{name}}/{{service}}                     # k8s/prod/api
      destination:
        namespace: payments-{{name}}-{{service}}           # payments-prod-api

Branch Strategy​

Prefer folder-based env separation (k8s/{env}/) over branch-per-env. Branches make cross-env diffs and promotions harder.

platform-gitops / {domain}-gitops   →  main only (no env branches)
ArgoCD                              →  always tracks HEAD of main

CODEOWNERS Enforcement​

# platform-gitops
/argocd/              @myorg/team-platform
/crossplane/          @myorg/team-platform
/k8s/rbac/            @myorg/team-platform
/backstage-templates/ @myorg/team-platform

# {domain}-gitops
/k8s/                 @myorg/team-{domain}
/crossplane/claims/   @myorg/team-{domain}
/catalog/             @myorg/team-{domain}
/.github/             @myorg/team-platform  @myorg/team-{domain}