Promotion by Git ref — the Git reference moves; the artefact is built per environment

Promotion by Git ref is the model in which the environment repository’s commit is the unit of release. The CI pipeline renders the manifests for the target environment, writes the rendered YAML to the environment repo, and the GitOps controller reconciles each environment against its own commit. The commit at the tip of the dev branch, the commit at the tip of the staging branch, and the commit at the tip of the production branch are three different commits, each pinning the manifest that environment is meant to run.

The promotion shape

The diagram is the model. The application source is rendered per environment, and the rendered manifests are written to separate branches or paths in the environment repository. The Argo CD Application for dev tracks the dev branch; the staging Application tracks the staging branch; the production Application tracks the production branch. Promotion is the act of moving the rendered manifest from one branch to the next.

flowchart LR
    A["App source: commit X"] --> R["Render pipeline"]
    R --> D["dev branch: commit a3f9d2"]
    R --> S["staging branch: commit b7c1e1"]
    R --> P["prod branch: commit c4d8f3"]
    D --> AD["Argo CD: dev Application"]
    S --> AS["Argo CD: staging Application"]
    P --> AP["Argo CD: prod Application"]

The rendered manifests are different because each environment has different values: replica counts, resource limits, ingress hostnames, secrets references. The dev manifest may use replicas: 1 and an internal.example.com hostname; the production manifest may use replicas: 6 and the public hostname. The diff between the dev commit and the production commit is the environment-specific difference.

Reconciling by Git ref

The Argo CD Application’s --revision flag accepts a Git ref when the source is a Git repository. For promotion by Git ref, the revision is the branch or tag the environment Application tracks.

DEV_SHA=$(git -C env-repo rev-parse origin/dev)
STAGING_SHA=$(git -C env-repo rev-parse origin/staging)
PROD_SHA=$(git -C env-repo rev-parse origin/production)
argocd app set payment-api-dev --revision "$DEV_SHA"
argocd app set payment-api-staging --revision "$STAGING_SHA"
argocd app set payment-api-prod --revision "$PROD_SHA"
argocd app sync payment-api-prod --revision "$PROD_SHA"

Each Application is pinned to its own ref. The sync against production reconciles only the production commit; the dev and staging Applications are unaffected. The audit record per environment is the Git commit the Application tracked at the moment of sync.

The audit shape and the rollback

The audit record per environment is the Git commit. “What is running in production?” is answered by the production branch’s HEAD at the time the controller last reconciled. The roll- forward is a new commit on the production branch. The rollback is git revert of the production commit:

git -C env-repo revert --no-edit production
git -C env-repo push origin production
argocd app sync payment-api-prod

The revert restores the previous manifest, which references the previous artifact. The cluster reconciles to the previous bytes; the production branch’s history shows both the bad commit and the revert. The audit trail is the Git log, and the rollback is a Git operation.

When the artifact is built per environment

A Git ref promotion does not require per-environment rebuilds, but it permits them. Some teams render the manifest with a different image tag per environment: the dev branch pins the latest main commit’s image, the staging branch pins the release candidate’s image, the production branch pins the released image. In that case, the artifact differs per environment, and the promotion is no longer “build once, deploy many” — it is “build per environment, reconcile per environment”. The audit story is still the Git commit per environment, but the supply-chain story requires per- environment signing.

Production discipline

The production rules for promotion by Git ref:

1. Each environment has its own ref. The dev, staging, and production branches are not interchangeable. The Argo CD Application per environment tracks its own ref.
2. The rendered YAML is the audit unit. The diff between the previous commit and the new commit is what changed in that environment. The review must cover that diff.
3. The rollback is a Git operation. git revert restores the previous manifest; the controller reconciles to the previous bytes. The rollback handle is the Git log, not a registry tag.

Cross-course references

• Git, CI/CD & GitOps — Part LXXVI-05 (Promotion models) establishes the artifact vs Git ref taxonomy this lesson implements.
• Git, CI/CD & GitOps — Part XLV-03 (Promotion across environments) contrasts with this lesson’s per-environment rendering.
• Kubernetes for Production Sysadmins — Part V (Workloads) covers the runtime config injection that determines whether per-environment rendering is necessary.

Quiz