Learn GitOps with ArgoCD - GitOps Workflow & Branch Strategies

#Introduction

In episode 14 we scheduled when syncs may happen with Sync Windows. Now all the technical components are complete — Application, Project, ApplicationSet, Secrets, Hooks, and Windows. But there's one layer that's often forgotten and actually determines a team's success: the human workflow around Git. How do changes flow from a developer's laptop to the production cluster? In this episode we discuss GitOps Workflow & Branch Strategies — the repository, branch, and promotion patterns that make Git truly an organized source of truth.

Why does this matter? ArgoCD only does what's in Git. If the Git structure is messy, the result is messy deployments. Conversely, a well-organized GitOps repository is part of the control mechanism: every change is reviewed, documented, and easy to roll back — exactly what's needed for audits and operations at scale.

#Git Workflow Patterns

There are three major patterns determining how teams write changes:

#Trunk-Based Development

All developers work on a single main branch (usually main), with features developed in short-lived branches that are quickly merged via PR. Advantages: continuous integration, minimal conflicts, and a linear history. This is the pattern best suited to GitOps because ArgoCD syncs one clear targetRevision.

#GitFlow

Uses the develop branch as the development center with feature/* + release/* + hotfix/* branches around it. More structured for big releases, but heavier: changes must pass through several branch levels, and this often makes GitOps configuration duplicative.

#Environment Branches & Release Branches

An intermediate pattern: one branch per environment (dev, staging, prod). ArgoCD in the dev environment syncs the dev branch, and so on. Promotion is done by merging between branches. Release branches (release-1.2) are used to lock the version being released — well combined with tags.

#Repository Directory Structure

Besides branches, the directory structure determines the scale of a GitOps repository. Three common approaches:

#Environment-Based

gitops-repo/
├── apps/
│   ├── billing/
│   │   ├── base/
│   │   ├── overlays/
│   │   │   ├── dev/
│   │   │   ├── staging/
│   │   │   └── prod/
│   └── orders/
└── clusters/
    ├── dev/
    └── prod/

Every application has a base (default) and per-environment overlays. Promotion = adding or changing an overlay. This is the most common and easiest-to-understand pattern.

#Application-Based & Cluster-Based

• Application-based — one directory per application containing all its manifests, often combined with an application monorepo.
• Cluster-based — one directory per cluster containing all the manifests for that cluster, well suited to multi-cluster (episode 9) because each cluster's contents are explicit.
• Hybrid — combining both: per cluster, then per application within it.

gitops-repo/
├── clusters/
│   ├── eks-prod/
│   │   ├── namespace-billing/
│   │   ├── namespace-orders/
│   │   └── platform/
│   └── kind-staging/
│       ├── namespace-billing/
│       └── namespace-orders/
└── apps/
    └── shared-charts/

#Promotion Strategies

Promotion is the process of moving a change from a lower environment to a higher one. Four strategies:

The pattern highly recommended for production is tag-based + PR promotion: the team promotes by creating a PR that changes the image version in the prod overlay to a specific tag, and ArgoCD only applies it if the PR is approved.

Prod overlay pointing to a tag

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
images:
  - name: ghcr.io/devnull/billing-api
    newTag: v1.2.3

#Change Management

This part is what makes GitOps excel at governance:

• PR reviews — every change to the GitOps repository must go through a PR with reviewers who understand the target environment. Branch protections (required reviews) make it hard to bypass.
• Approvals — for production, give dedicated CODEOWNERS (e.g. the platform team) and require approval — can be reinforced with CI status checks.
• Change tracking — because every change is a commit, each deployment can be traced back to its PR and related issue. Use conventional commits (per AGENTS.md) so changelogs are generated automatically.
• Rollback procedures — rollback in GitOps is a revert commit (or argocd app rollback for a previous state). Since manifests are versioned, reverting is always possible and documented.

#Common Pitfalls

1. Many environment branches that drift apart. A prod branch merged manually without a clear promotion flow quickly diverges from staging. Standardize the promotion flow.
2. Manifests edited directly in the cluster. This violates GitOps principles and creates drift; ArgoCD will restore the Git state.
3. Rolling back by rewriting history. Don't git push --force to "make changes disappear"; use revert so the audit trail stays intact.
4. A constantly changing directory structure. Re-arranging the layout every month makes Applications and ApplicationSets inconsistent. Decide once, document it.
5. Versioning images without meaningful tags. latest is hard to roll back and not reproducible. Mandate semver (we dive into this in episode 16).

#Closing

This episode summarized the human side of GitOps: the comparison of trunk-based, GitFlow, and environment branches, environment-based/application-based/cluster-based directory structures, branch/tag/PR/overlay promotion strategies, and change management through PR reviews, approvals, change tracking, and rollback procedures.

The points you should take with you:

• A tidy GitOps repository is a control mechanism, not just a place to store files.
• Trunk-based + tag-based promotion is the most modern and safest combination.
• Separate the app repo and the GitOps repo for different permissions.
• Every production change must go through a PR and review.
• Rollback = revert commit; don't rewrite history.

Keeping image versions in sync between environments manually is very tiring. In the next episode 16 we discuss Image Updater - Automated Image Updates: installing ArgoCD Image Updater, semver/latest/digest strategies, write-back to Git, and patterns from automatic dev to manual approval in production. See you in episode 16!