Repository and environment boundaries

A repository layout is a collaboration decision

A source repository holds application code and build instructions. A desired-state repository, or a protected directory in the same repository, holds the configuration a controller watches. Separating them can make ownership clearer, but only enforced permissions and review rules decide who may change an environment.

Open the ownership diagram at full size. This is the intended ownership map, not proof that every configuration is implemented in the selected repository revision.

Separate responsibilities before repositories

MicroBank can keep source and local manifests in one repository while learning. A production design might separate application source from environment configuration because different people review them. The number of repositories does not establish security: access rules, trusted automation, branch protections, and controller permissions do.

Choose one desired-state branch with environment directories for the first exercise. Long-lived branches per environment introduce merge and drift questions; they are not required for environment separation. A release PR should make the intended target and artifact identity easy to inspect.

Protect the path to reconciliation

An unreviewed commit to the branch Argo CD watches can bypass a pipeline’s approval gate. Similarly, a restrictive repository policy is insufficient if someone can edit the Application to watch their own repository. Consider both the desired-state data and the controller configuration.

Use repository rules and required checks appropriate to the actual account plan. CODEOWNERS identifies review responsibility; enforce required owner review where supported. Do not assume a CODEOWNERS file alone blocks merging.

Trace one commit through the boundary

Suppose a contributor opens a PR that changes Ledger and its Dockerfile. Offline checks can run without deployment credentials. After the trusted build process publishes an approved image, a separate change selects that image in the local overlay. Argo CD reads the reviewed configuration and reconciles it.

Now try two bypasses. First, someone pushes directly to the watched branch: required PR review must be enforced to stop that path. Second, someone changes the Application's repository or revision: protect controller configuration too. A pipeline approval does not help if a different path can change the watched state.

For the local exercise, one repository with clear directories is sufficient. Document where these decisions are enforced in your actual repository account; do not imply that a CODEOWNERS file alone provides them.

Try it

Make a small permission matrix for developer, reviewer, build identity, GitOps controller, and portal backend. Cover source write, environment write, repository read, cluster write, and secret read. Grant each role only the access its task requires.

Then trace a change from a forked pull request. Rendering and offline policy checks need no cluster credentials. Publishing artifacts or changing deployment state should run through a trusted workflow with a narrowly scoped identity. Do not execute untrusted repository scripts with deployment secrets merely because a PR has a label.

Checkpoint and revision

Identify two ways your intended approval could be bypassed and the concrete control for each. Git history records changes; authorization and required checks determine who may make them.

Compare your reasoning

Choose repository boundaries for review and ownership needs, not folder aesthetics. A forked PR can supply malicious build instructions, so publishing or deployment must not inherit its untrusted execution context and privileged credentials.

Sources

GitHub CODEOWNERS↗, GitHub secure Actions use↗, Argo CD security considerations↗.