The promotion decision — which model fits which organisation

The promotion model is the most consequential GitOps decision a team makes. The model determines the audit unit, the rollback shape, the supply-chain trust posture, the access-control boundary, and the operational discipline. Choosing the wrong model is not a bug that surfaces in code review — it is a bug that surfaces six months later when the regulator asks a question the model cannot answer. This lesson synthesises the four shapes into a decision framework that maps organisation shape to promotion model.

The decision dimensions

Four dimensions drive the choice:

• Supply-chain posture. Does the team sign the artifact or the manifest? Signing the artifact favors the artifact promotion model. Signing the manifest favors the Git-ref or environment-repo models.
• Organisational structure. Is the team monolithic or federated? A monolithic team can run one env repo with branches; a federated organisation needs per-team repos and per-team promotion bots.
• Scale. How many services, how many environments, how many clusters? Hand-maintained Applications scale to dozens; Applicationsets scale to thousands.
• Audit requirement. What question must the model answer? “What bytes ran?” is the artifact model’s native question. “What commit ran?” is the Git-ref model’s native question. “Who approved?” is the environment-repo model’s native question.

flowchart TD
    Q["What question must the model answer?"] --> D1["What bytes ran"]
    Q --> D2["What commit ran"]
    Q --> D3["Who approved"]
    D1 --> A["Artifact promotion"]
    D2 --> G["Git-ref promotion"]
    D3 --> E["Environment-repo promotion"]
    A --> S["Scale > 30 services x 4 envs?"]
    G --> S
    E --> S
    S -->|"yes"| AS["Wrap in ApplicationSet"]
    S -->|"no"| M["Hand-maintained Applications"]

The diagram captures the flow. The audit question determines the model. The scale determines whether the model is implemented directly or wrapped in an Applicationset.

The four shapes in one sentence

Each of the previous lessons has a one-sentence summary:

• Artifact promotion. The CI pipeline builds once; every environment pins the same digest; the SHA-256 is the audit unit.
• Git-ref promotion. The CI pipeline renders per environment; each environment’s commit is the audit unit; the rollback is git revert.
• Environment-repo promotion. Each environment has its own Git repository; the access-control boundary is the repo; promotion is a cross-repo PR.
• Applicationset promotion. The Applications are derived from generators; the generator input is the source of truth; adding a service or environment is a generator change.

Decision matrix

The matrix is not a recommendation; it is a tool. The team weights each dimension against its own organisation and picks the column that fits.

Documenting the choice

The promotion model is documented in the team’s GitOps README. The README names the model, names the audit unit, names the rollback shape, and links to the regulator-facing audit record. A new engineer reads the README and learns the model in one sitting. An auditor reads the README and knows which question the model can answer and which it cannot.

argocd app set payment-api-prod --revision "$DIGEST"
argocd app sync payment-api-prod --revision "$DIGEST"

The argocd commands work in every model. The --revision flag accepts a digest (artifact promotion), a Git ref (Git-ref or environment-repo promotion), or the rendered commit an Applicationset emits (Applicationset promotion). The operational shape is the same; the architectural shape is what the README documents.

Migration between models

A team that picked the wrong model can migrate, but the migration has a cost. Moving from Git-ref promotion to artifact promotion requires re-rendering every environment’s manifest with a digest-pinned image, signing the digest, and verifying the signature at sync time. Moving from environment- repo promotion to Git-ref promotion requires merging the env repos into one repo with branches and re-establishing the audit chain. The migration is not impossible, but it is a project; a team that anticipates the migration cost in the decision phase makes a more durable choice.

Production discipline

The production rules for the promotion decision:

1. The model is documented in the README. One model, one README section, one audit record format. New engineers learn the model from the README.
2. The audit record answers the regulator’s question. The model is chosen so the regulator’s question is the model’s native question. If the question is “what bytes ran?”, the model is artifact promotion. If the question is “what commit ran?”, the model is Git-ref promotion.
3. Mixed models are collapsed, not accommodated. The first incident that exposes the cost of a mixed model is the trigger to consolidate. A team that accommodates the mixed model is paying a tax it does not realise it is paying.

Cross-course references

• Git, CI/CD & GitOps — Part LXXVI-05 (Promotion models) establishes the two-model taxonomy this lesson extends to four shapes.
• Git, CI/CD & GitOps — Part XLV-03 (Promotion across environments) is the conceptual foundation.
• Terraform for Production Sysadmins — Part XXII (Plan files) covers the analogous decision in Terraform: the plan file is the unit of release, and the choice between re-planning per environment and reusing the plan file mirrors the Git-ref / artifact promotion trade-off.

Quiz