Promotion windows and approvals — the time-bound gates

A GitOps controller that reconciles automatically is fast and correct, but it is also indiscriminate: it will sync at 03:00 on a Saturday, it will sync during a freeze period, and it will sync a change that has cleared the build pipeline but has not cleared the operations team. Promotion windows and approvals are the time-bound gates that introduce operational discipline without sacrificing the GitOps property that the cluster converges to a known desired state.

Sync windows

A sync window is a controller-level rule that allows or denies syncs during a time interval. Argo CD’s sync windows support allow (syncs are permitted inside the window and denied outside) and deny (syncs are blocked inside the window and permitted outside). The window can be recurring (every Tuesday from 09:00 to 17:00) or one-shot (between two timestamps), and it can apply to specific Applications or to all Applications in a project.

flowchart LR
    A["CI: digest written"] --> W["Sync window check"]
    W -->|"in window"| S["Sync allowed"]
    W -->|"out of window"| H["Sync held"]
    H -->|"window opens"| S
    S --> AR["Argo CD reconcile"]
    AR --> P["Production state converged"]

The diagram captures the gate. The CI pipeline writes the digest; the controller checks the sync window; if the sync is inside the window it proceeds, if it is outside the window it is held until the window opens. The controller does not discard the change — the desired state is still in Git — it delays the convergence.

Manual approvals

A manual approval is a human gate that must be cleared before a sync proceeds. In Argo CD, this is implemented by disabling auto-sync and requiring an operator to run argocd app sync explicitly. In Flux, it is implemented by requiring a manual flux reconcile kustomization invocation, often driven by an external approval system that posts a webhook to the Flux notification controller.

argocd app set payment-api-prod --sync-policy manual
argocd app set payment-api-prod --revision "$PROD_SHA"
argocd app sync payment-api-prod --revision "$PROD_SHA"

The --sync-policy manual flag disables automatic sync. The set --revision updates the desired revision; the sync command is the human gate — only an operator with the right RBAC permissions can issue it. The audit trail is the operator’s CLI invocation, joined to the Argo CD audit log.

Freeze periods

A freeze period is a deny window applied to every Application in a project. December freeze, code-freeze before a major release, change freeze during a security incident — all are implemented as deny windows that overlap with the project. A hotfix during a freeze is a deliberate override: the operator opens a one-shot allow window, syncs, and the deny window reasserts itself. The audit trail is the deny window’s history plus the one-shot allow window’s history.

The interaction between windows and approvals

A production promotion typically has both: a sync window that allows syncs only during business hours, plus a manual approval gate. The CI pipeline writes the digest; the controller sees the new desired state but auto-sync is disabled; the operator reviews and runs argocd app sync during the next window; the cluster converges. The window is the time gate; the approval is the human gate; together they ensure production changes happen with operational discipline.

Failure modes

Three failure modes recur:

• Missed window. A change is merged at 16:55 and the window closes at 17:00. The sync is held; the team is unaware. The fix is alerting on OutOfSync Applications whose window has just closed.
• Orphaned approval. An approval is recorded but the underlying change is reverted before the sync. The approval refers to a digest that is no longer the desired state. The fix is binding the approval to a specific digest at approval time, not to a change description.
• Override without audit. A hotfix bypasses the window with a manual sync. If the override is not recorded, the audit trail has a gap. The fix is requiring a one-shot allow window with a recorded reason rather than an out-of-band sync.

Production discipline

The production rules for promotion windows and approvals:

1. Sync windows are project-level. A team that puts production syncs in a manual window should configure the window on the project, not on each Application. One rule, many Applications.
2. Approvals reference the digest, not the change. An approval that references a digest is durable; an approval that references a commit is durable; an approval that references a change description is fragile.
3. Overrides are auditable. A hotfix outside the window is a one-shot allow window with a recorded reason. The override is in the window’s history, not in someone’s memory.

Cross-course references

• Git, CI/CD & GitOps — Part LXXXI (Synced/healthy) covers the OutOfSync state that a held sync produces.
• Git, CI/CD & GitOps — Part LXXVI-05 (Promotion models) establishes the promotion shapes that windows and approvals gate.
• Kubernetes for Production Sysadmins — Part XXXV (Change management) covers the change-advisory process that integrates with manual approval gates.

Quiz