Federated Monorepo Architecture

The two-tree GitLab group layout — comptech-platform vs divisions — the eleven ct-* role groups, repository ownership, and the boundaries that keep app teams off platform state.

The lab’s GitLab is organized as a federated monorepo by ownership boundary: two sibling group trees, one for platform-owned operational state, one for application-team state. The split is not stylistic. It exists to make the OpenShift GitOps pull model enforceable, and to keep application teams structurally unable to write to platform state.

This page covers the architecture, the ownership matrix, the role-group model, and the CODEOWNERS baselines. ADR 0023 locks the design in.

Architecture

The two trees:

• comptech-platform/ contains platform-owned operational state — OpenShift cluster GitOps, VM platform-ops, platform tools, tenant registry.
• divisions/ contains application-team state, organized one sub-group per division. The lab’s current bootstrap division is sandbox.

Why two trees, not one

Per ADR 0023 the alternatives considered include:

The two-tree split is cheap to operate and gives the OpenShift/platform team a defensible namespace boundary. It is the lock-in decision.

Group layout (live)

The skeleton already exists in the live GitLab:

comptech-platform/
  openshift-ops/
    openshift-platform-gitops   (project ID 12 — live)
    openshift-cluster-build     (planned)
  infra-ops/
    vm-platform-ops             (planned)
  platform-services/
    platform-tools-iac          (deferred)
    platform-tools-config       (deferred)
  tenant-registry/
    openshift-tenants           (deferred)

divisions/
  sandbox/
    openliberty-readiness-probe (live source repo)
    demo-smoke                  (live source repo)
    sandbox-apps-monorepo       (planned)
    sandbox-gitops              (planned)

The first live repo is openshift-platform-gitops (project ID 12). It was migrated from gitops/platform-gitops to comptech-platform/openshift-ops/openshift-platform-gitops as part of the bootstrap. The local clone on operator workstations is at /home/ze/platform-gitops and points at the LAN endpoint.

Repository ownership matrix

Application teams must not write to:

• openshift-platform-gitops
• openshift-cluster-build
• vm-platform-ops
• Platform runner or admin configuration repos

Creation order

Not every repository above must exist immediately. The accepted creation order per ADR 0023:

1. openshift-platform-gitops (live, project ID 12).
2. vm-platform-ops when ownership and first service adoption are ready.
3. openshift-cluster-build when cluster-build artifacts are ready to split out of planning docs.
4. platform-tools-iac, platform-tools-config, openshift-tenants only when their split proves useful.
5. Division repositories as teams onboard.

Role groups (eleven ct-* groups)

Individual users are added to role groups, not directly to projects, except for tightly scoped temporary exceptions recorded against an issue.

The bootstrap sandbox already has ct-sandbox-app-maintainers, ct-sandbox-developers, and ct-sandbox-release-approvers instantiated.

Initial project shares (openshift-platform-gitops)

Project ID 12 is shared with:

• ct-openshift-platform-maintainers: Maintainer
• ct-openshift-platform-reviewers: Reporter
• ct-security-reviewers: Reporter
• ct-auditors: Reporter

ct-sandbox-* groups have no access to platform GitOps. The same pattern is applied to each new operational repo as it’s created.

CODEOWNERS baseline

The CODEOWNERS files express path-level review ownership and complement project shares. The lab baseline:

openshift-platform-gitops

/clusters/       @ct-openshift-platform-maintainers
/components/     @ct-openshift-platform-maintainers
/policies/       @ct-openshift-platform-maintainers @ct-security-reviewers
/tenants/        @ct-openshift-platform-maintainers @ct-security-reviewers
/bootstrap/      @ct-openshift-platform-maintainers

Future vm-platform-ops

/services/haproxy/        @ct-infra-platform-maintainers
/services/pdns/           @ct-infra-platform-maintainers
/services/gitlab/         @ct-infra-platform-maintainers
/services/jenkins/        @ct-infra-platform-maintainers @ct-cicd-platform-maintainers
/services/nexus/          @ct-infra-platform-maintainers @ct-cicd-platform-maintainers
/services/docker-runtime/ @ct-infra-platform-maintainers
/services/gitlab-runner/  @ct-infra-platform-maintainers @ct-cicd-platform-maintainers @ct-security-reviewers
/terraform/               @ct-infra-platform-maintainers
/ansible/                 @ct-infra-platform-maintainers
/policies/                @ct-infra-platform-maintainers @ct-security-reviewers

Division app GitOps

/apps/*/dev/      @ct-<division>-app-maintainers
/apps/*/uat/      @ct-<division>-release-approvers
/apps/*/staging/  @ct-<division>-release-approvers
/apps/*/prod/     @ct-<division>-release-approvers @ct-security-reviewers

Review rules

Per ADR 0023, the minimum approval expectations are fixed:

Where GitLab CE cannot enforce a rule natively, compensating controls — CODEOWNERS, protected branches, validation pipelines, MR evidence — must be recorded.

OpenShift GitOps boundary

openshift-platform-gitops owns OpenShift operations only:

• Cluster bootstrap paths
• ACM/MCE and OpenShift GitOps control
• Mirrored CatalogSources and ClusterCatalogs
• IDMS/ITMS mirror configuration
• Platform operators
• Storage layer configuration
• Tenant namespaces and AppProjects
• Quotas, limit ranges, NetworkPolicies, RBAC, and policy guardrails

It does not own:

• Application source code
• Routine application release manifests
• VM-hosted platform tool configuration
• Kafka or other middleware (unless explicitly introduced as an OpenShift platform workload through a tracked issue and ADR)
• Generic Docker image catalogues

Onboarding a new division

When the time comes:

1. Create divisions/<division>.
2. Create role groups: ct-<division>-app-maintainers, ct-<division>-developers, ct-<division>-release-approvers.
3. Create <division>-apps-monorepo.
4. Create <division>-gitops.
5. Add README, CODEOWNERS, MR template, and validation pipeline.
6. Grant app teams only to division repos.
7. Register tenant boundaries in platform-owned OpenShift GitOps (namespaces, AppProjects, quotas, limit ranges, NetworkPolicies, RBAC, allowed source repos, allowed destination namespaces).
8. Run negative access tests.
9. Run a golden-path app smoke test before production onboarding.

Stop and revisit the design if the division needs write access to openshift-platform-gitops for normal application deployment — that means the tenant/AppProject model is wrong or incomplete.

Residual decisions (still open)

ADR 0023 explicitly leaves these open for separate tracking:

• Final naming for the existing ct-* role groups if the eleven-group list proves too coarse or too fine in practice.
• Whether openshift-tenants should be a separate repo or a folder inside openshift-platform-gitops.
• Whether platform-tools-iac and platform-tools-config should be separate repos immediately or deferred.
• Whether application GitOps repositories should be one per division or one per application for high-risk teams.
• Whether production branches should require signed commits immediately or in a later hardening phase.
• The GitLab CE merge-control and CODEOWNERS-enforcement decision under FG-1.

References

• opp-full-plat/adr/0023-federated-gitlab-group-repo-ownership.md — ownership model.
• opp-full-plat/adr/0015-federated-gitops-repo-architecture.md — parent architecture.
• opp-full-plat/adr/0016-workspace-execution-governance.md — operator workspace rules.
• opp-full-plat/connection-details/gitlab-operator-guide.md — operator runbook.
• opp-full-plat/plans/federated-gitops-gitlab-access-matrix.md — full access matrix (the source-of-truth design baseline).
• opp-full-plat/plans/federated-gitops-gitlab-implementation-checklist.md — execution sequence.