How Argo CD sync windows control change freezes
A release freeze or maintenance window has to stop changes from reaching production through GitOps, and in Argo CD the mechanism for that is the sync window. A sync window is either an *allow* window or a *deny* window, defined by a cron schedule, a duration and an optional timeZone. If no time zone is set, the schedule is evaluated in UTC, so a freeze written for a regional business day will start at the wrong hour unless the time zone is stated explicitly. Teams usually need deny windows for change freezes around month-end close, peak trading or a regulated reporting period, and allow windows for maintenance periods when they want automated syncs to run only at agreed times.
The rule to plan around is that allow windows act as a whitelist: if any matching allow window exists, automated syncs are permitted only while one is active. A deny window blocks syncs while it is active, and when a deny and an allow window overlap, the deny wins. Windows can be scoped to applications, clusters or namespaces with wildcards, so a freeze can cover one production cluster and leave staging untouched. Before relying on this, confirm in a non-production Argo CD instance how the selectors match your application names, cluster names and namespaces, because a pattern that is too broad will freeze more than intended.
Sync windows govern syncs that Argo CD performs. They do not stop someone with cluster access from running kubectl apply, and they do not stop a pipeline that writes directly to the cluster, so a freeze also needs Git branch protection, cluster RBAC and change tickets behind it. Confirm with your own team which change paths exist for each production cluster before you describe the freeze to auditors or business owners as a complete control.
Sync window options and when each fits
This table compares each sync window option against the change freeze or maintenance scenario it serves and the mistake teams most often make with it. Read each row as a decision: choose the option that matches the control you need, then check the common mistake before writing the window. The main takeaway is that deny windows and allow windows behave differently, and selector logic decides which applications a window actually touches.
| Option | When it fits | Common mistake to avoid |
|---|---|---|
| Deny window | Freezing all automated syncs during a release freeze or an audit-sensitive period | Assuming a deny window also blocks manual syncs, which depends on the manualSync setting |
| Allow window | Permitting automated syncs only during an approved maintenance slot | Adding one allow window and forgetting that every other hour is then blocked for matching applications |
| Cron schedule | Expressing a recurring weekly change slot or a fixed freeze start time | Writing cron fields for the wrong day order or forgetting that the window runs for its duration only |
| Duration | Setting how long a freeze or maintenance slot stays active after the cron start | Setting a duration shorter than the expected release, so the window closes mid-rollout |
| timeZone | Aligning a window with the business hours of the team that approves changes | Leaving the default UTC when approvers work in another zone, shifting the freeze by hours |
| Application, cluster and namespace selectors | Targeting one service, one destination cluster or one namespace with wildcards | Using a broad wildcard that unintentionally blocks unrelated production applications |
| manualSync | Letting an on-call engineer apply an urgent fix while automated syncs stay blocked | Enabling it on a deny window without a documented approval step, which lets manual changes bypass the freeze |
| andOperator | Requiring an application, namespace and cluster to all match before a window applies | Leaving the default OR logic, so a window meant for one cluster catches every application in a namespace |
How to set up a release freeze with sync windows
This sequence turns a change freeze agreed by the business into Argo CD sync windows that block automated syncs on the right applications, with a tested path for emergency fixes. Each step ends with a check, so the freeze is proven to work before the next one starts.
Confirm the freeze calendar and owners
Before any YAML is written, the release manager and the platform owner agree on the freeze dates, the time zone the business uses, which applications and clusters are covered, and who may approve an emergency sync during a freeze. Record these in the change calendar with named owners. The step is done when the written calendar lists each freeze with its start, end, time zone and approver, and the platform owner has confirmed that the time zone matches what the business quoted.
Define the project and its selectors
Place the affected Applications in an Argo CD project so the windows apply to a bounded set of workloads. Identify the selectors you need: application names, destination clusters and destination namespaces, using wildcards where naming conventions allow. Confirm that no application outside the freeze scope matches. Verify by opening the project in the Argo CD UI or with the CLI and listing the Applications it contains, then comparing that list with the calendar from the previous step.
Write the deny windows with cron and time zone
Add a deny window to the project's syncWindows list. Set the kind to deny, the schedule to a cron expression that starts the freeze, the duration to cover the freeze period, and timeZone to the zone agreed in step one, since the default is UTC. Add the selectors from step two. Commit the change through Git so the freeze is reviewed like any other change. The step is done when the manifest merges and the project shows the window in its sync window status.
Check overlapping allow windows
If the project already has allow windows, review them now. When any matching allow window exists, syncs are permitted only while one is active, so an allow window that overlaps the freeze does not lift the block, but a gap in allow coverage can stop routine syncs outside the freeze. Deny windows override allow windows when they overlap. Confirm the resulting behavior for a normal day and for a freeze day, and record both in the change notes.
Decide on manualSync for emergency fixes
Decide whether engineers may run a manual sync while the deny window is active. Setting manualSync to true lets manual syncs run while the window blocks automated syncs, which suits a narrow emergency path but also means a person can deploy during a freeze. Agree who holds that permission and document it in the runbook. Verify the decision by confirming the setting in the manifest and by testing it in a non-production project before relying on it.
Set andOperator where selectors must match together
By default, the application, namespace and cluster selectors combine with OR, so a window applies if any selector matches. Set andOperator to true where the window should apply only when application, namespace and cluster all match, for example to freeze one service in one cluster without blocking the same service elsewhere. Review each selector set against the inventory from step two. The step is done when a dry review shows the intended applications matched and no others.
Test with a window that is active now
Create a short test window that is active at the time of the test, scoped to a non-production application, and attempt an automated sync and a manual sync. Confirm the automated sync is blocked and that manual behavior matches the manualSync decision. Check the project's sync window status while the window is active, then remove the test window. Do not rely on the production freeze until this check passes, and record the result, including the time zone used, in the change record.
Verify the production freeze before it starts
Shortly before the freeze begins, open the project's sync window status and confirm that the production deny window is listed with the expected schedule, time zone and selectors. Attempt a sync of one covered application to confirm the block, and confirm that an application outside scope still syncs. Ask the release manager to sign off on the result. The step is done when the sign-off and the test results are stored with the freeze calendar.
Who can change or override a sync window
A sync window is only as reliable as the people and permissions around it. The cards below cover who can edit a window, who can bypass one, and which controls keep a freeze in place during a release.
AppProject edit rights
Sync windows are defined on the AppProject resource, so anyone who can edit that project can add, change or remove a freeze. A deny window can be deleted in the same commit that ships an unrelated change. Confirm which groups hold update rights on AppProject objects, and whether those rights are limited to a platform team in the argocd namespace.
Manual sync override
The manualSync setting lets operators run syncs by hand while a window blocks automated syncs. That is useful for hotfixes, but it also means a freeze stops automation rather than people. Decide who may trigger manual syncs during a freeze, and record each override with a reason so the exception is visible afterward.
Application-level RBAC in 3.0
From Argo CD 3.0, update and delete RBAC apply only to the application itself, so a user who can sync an application may not be able to change the project that contains its windows. Review your policy after upgrading, since the rule changes what a team lead can do. Check the upgrade notes against your existing role definitions.
Project boundaries and destinations
Projects limit which repositories, clusters and namespaces an application may use. An application moved into a project without a freeze window escapes the freeze entirely. Confirm that applications cannot be reassigned to another project by users outside the change board, and that the project list is reviewed alongside the window list.
Git review as the control point
Window definitions live in Git when managed declaratively, so a pull request is the audit trail for every change to a freeze. Require review from someone outside the team that owns the project, and block direct pushes to the branch Argo CD watches. Without that gate, the window is only as strong as the cluster's admin password.
Admin account and SSO groups
The built-in admin user can change any project, so it bypasses every RBAC rule above. The user management guidance recommends disabling it with admin.enabled set to false once SSO or local users are configured. Confirm that only break-glass accounts can reach project objects, and that group mappings for freeze approvers are reviewed on a schedule.
Sync window questions buyers ask before hiring help
What drives the effort and cost of setting up Argo CD sync windows?
The main drivers are how many AppProjects you have, how many clusters and namespaces the windows must target, how many distinct freeze and maintenance calendars the business uses, and how much approval flow sits around each change. Each project that needs its own windows adds design and review work, and each calendar adds rules that must be tested against time zones and overlaps. Setup is usually a one-time cost, while calendar upkeep recurs every time the business changes its freeze dates. Ask any partner for a quote that lists projects, clusters, calendars and the approval steps separately, so you can see which part scales with your estate.
How long does it take to configure sync windows for a release freeze?
The duration depends on the same inputs as cost: the number of projects, clusters and calendars, and whether your change calendar is already written down. A team with a single project and one clear freeze calendar can configure windows quickly, while a multi-team estate needs time to agree on which applications each window covers. Testing takes real time too, because you should confirm that allow and deny windows behave as expected across time zones and overlapping periods before the first freeze. Ask for a written timeline tied to the agreed scope rather than a generic estimate.
What does our team need to provide before sync windows can be designed?
You need a dated freeze and maintenance calendar, named owners who can approve changes to it, and a clear list of which applications, clusters and namespaces each freeze affects. The RBAC design also matters, because the people allowed to run manual syncs during a block must be identified in advance and mapped to your roles. Confirm which time zone your change board uses, since windows default to UTC unless you set a time zone. Missing owners or unclear scope are the most common reasons a window design stalls.
Can our own platform team set up sync windows without outside help?
Yes, if your team already runs Argo CD and understands AppProjects and RBAC. Sync windows are defined in the project spec, so the configuration is a matter of writing cron schedules, durations and selectors, then testing them. The harder work is agreeing on the calendar and the override rules with the people who own releases, which is an organizational task rather than a technical one. A partner is most useful when the estate is large, when the windows must be reviewed for compliance evidence, or when your team has no capacity to test overlaps properly.
How do we keep sync windows current as freeze dates change?
Treat the window definitions as code stored in Git, so every change to a freeze date goes through a pull request with a named approver. Pair that with a recurring review tied to your change calendar, so windows are checked before each quarter or major release cycle. Stale windows are a common failure: a freeze that ended still blocks deployments, or a new holiday period is never added. Ask whether the partner will hand over a documented change procedure and a review checklist, and whether support or a retainer will cover calendar updates after go-live.
What should an emergency override process look like for a change freeze?
An emergency override should be narrow, approved in advance, and recorded. Manual syncs can run during a window that blocks automated syncs when manualSync is enabled, so decide which projects allow it and which roles may use it. Require a named incident or change ticket, a second approver for production clusters, and a log of who synced what and when. Avoid broad overrides that disable deny windows for everyone, because they remove the protection the freeze was meant to provide. Confirm with your security and change teams that this path matches your policy before enabling it.
How do overlapping allow and deny windows behave during a freeze?
A deny window blocks syncs when it is active, and deny windows override allow windows when they overlap. If any matching allow window exists, syncs are allowed only while one is active, so a freeze can be written as a deny window on top of a standing allow schedule. The andOperator setting changes how application, namespace and cluster selectors combine, from OR to AND, which can narrow a window considerably. Test these combinations in a non-production project before you rely on them, and confirm the behavior against the Argo CD sync windows guide for your Argo CD version.
Do sync windows count as compliance evidence for change control?
Sync windows help enforce change control, but they do not prove compliance on their own. They show that a schedule was configured and that automated syncs were blocked during defined periods, and that evidence is strongest when the windows live in Git with reviewed history. Auditors will still ask who approved the calendar, how overrides were authorized and logged, and how the configuration is tested. DeployOpen prepares systems, controls and evidence for compliance assessments, but independent auditors and certification bodies issue any audit report or attestation.
Running sync windows day to day
Treat every sync window as code. Windows are defined in the syncWindows list of an AppProject, so changes to a freeze should go through the same pull request review as application manifests, with the cron schedule, duration, timeZone and selectors visible in the diff. Have the person who owns the change calendar approve the pull request, and record the ticket reference in a comment next to each window. Remove expired deny windows once a freeze ends, because a forgotten one blocks syncs long after the business reason has gone. Review allow windows too. A single allow window makes every hour outside it a blocked hour for the applications it matches, which can surprise teams that expect syncs to run at other times.
Test each window before the freeze starts. Check that the cron expression and time zone produce the start and end times your change calendar uses, then confirm which applications, clusters and namespaces the selectors actually match, since wildcards often catch more than intended. During a freeze, watch for applications that drift from Git because their automated syncs are blocked. For an emergency fix, use a manual sync only where the window sets manualSync to true, and record who ran it, why, and which commit was deployed in the change ticket. The operation history on each application gives a partial trail, so confirm with your own logging and Kubernetes audit configuration what is retained and for how long.
Sync windows depend on the Argo CD version you run, so keep the controller on a supported minor line. The project ships a minor release four times a year and gives patch releases only to the three most recent minor versions. On October 12, 2026, the Argo CD release process lineage saw patch releases v3.5.5 (marked latest), v3.4.11 and v3.3.16, with v3.6.0 in release candidate. Schedule upgrades outside freeze periods, never inside one, and test the target version against a copy of your windows in a non-production cluster first. Confirm the current supported versions on the project's releases page before you plan.
Sync windows versus Git freezes and pipeline gates
Sync windows, branch protection, CI promotion gates and manual approval each block a different point in the path from commit to cluster. Most change freezes need more than one of them, and the gaps between them are where unplanned changes usually get through.
Sync windows stop the cluster, not the commit
A deny window blocks Argo CD from applying changes to matching applications, clusters or namespaces, but developers can still merge to the branch and CI can still build images. Argo CD tracks the change and applies it when the window closes. Check which automated syncs the window covers, and confirm whether manual syncs stay allowed through manualSync, since that setting is the most common source of surprise during a freeze.
Branch protection stops the merge
Branch protection in the Git host prevents commits from reaching the release branch, so nothing reaches Argo CD at all. It is the strongest stop for a freeze, but it also blocks hotfixes unless you define an exception path. Decide whether the freeze is enforced at the branch, at the sync, or at both, and record who can lift each one.
CI promotion gates control artifacts
Promotion gates in CI decide which image tag or rendered manifest moves into an environment's Git path. A gate can refuse promotion during a freeze, but it does not stop an already-promoted revision from syncing later. Pair the gate with a sync window so that a change promoted before the freeze does not apply during it.
Manual approval covers people, not timing
A manual approval step requires a named person to sign off before a change is promoted or synced. It is useful for exceptions, but it depends on the approver being available and on the approval being recorded. Ask who can approve during a freeze and where that approval is stored as evidence.
Overlapping controls create gaps
Each control has its own owner, schedule and exception path, so a freeze can be lifted in one place and still apply in another. Map every environment and application against each control before the freeze begins. Write a short test for each cluster, such as a dry run during the window, to confirm the controls agree.
Time zones and schedules need checking
Sync window schedules use cron expressions with an optional time zone, and the default is UTC. A freeze written for the head office's local time can start or end at the wrong hour for a team in another region. Confirm the time zone on each window and test the start and end times on a non-production cluster before the first real freeze.
How DeployOpen scopes and supports sync windows
DeployOpen plans and implements Argo CD sync windows as part of a self-hosted Argo CD deployment in infrastructure you control. We start from your change calendar and freeze policy, write the window rules into a fixed scope, and hand over the configuration with the tests and runbooks your release managers need.
How we scope
- We map your change freezes, maintenance windows and time zones before any window is written
- The written scope lists which Applications, clusters and namespaces each window targets
- We agree in writing whether manual sync overrides are allowed and who may use them
- Engagements are fixed-scope, so deliverables and timelines are confirmed before work starts
How we build
- We write allow and deny windows as code in the Argo CD configuration kept in Git
- Each window is checked against its cron schedule, duration and timeZone setting
- We test overlapping allow and deny windows so a freeze reliably overrides regular windows
- We verify the andOperator selector logic against the application, cluster and namespace matches agreed in scope
How we hand over
- You receive the window definitions, selector tables and the resolution rules in a written document
- Test cases show which syncs are blocked, allowed or overridden during a sample freeze (illustrative)
- A runbook explains how an on-call engineer uses a manual sync during a blocked window
- Your team walks through the change process so ownership of future window edits is clear
How we support
- Ongoing support is available as a retainer for window changes after each release calendar update
- Argo CD upgrades can change sync behavior, so window tests are rerun as part of the upgrade plan
- Confirm with your team and the Argo CD sync windows guide how your installed version handles each setting
- Continuous testing and periodic reviews of window coverage can be included in a retainer scope
