GitOps with Argo CD

Pathrule2 Rules • 3 Memories • 1 Skill

GitOps changes deployment authority: the cluster continuously reconciles toward a reviewed repository, so imperative fixes, generated manifests, secret injection, resource ownership, health checks, and sync ordering must all agree with that control loop. This pattern constrains desired-state authority and destructive sync behavior, records application boundaries, drift, health, and ordering decisions, and supplies a repeatable promotion and recovery workflow. It complements Kubernetes and GitHub Actions by focusing on continuous reconciliation after CI has produced an artifact and configuration change.

Suggested path map

Pathrule places each piece on the matching path, so your assistant only sees it where it belongs. This is the scoping you get on import; you can adjust it in your workspace.

/ workspace root

promote-argocd-change

gitops/

apps/

Make Git the only durable desired-state authority

An Argo CD application is an ownership and blast-radius boundary

Sync order is a declared dependency graph

platform/

Enable pruning only with explicit resource ownership

ops/

runbooks/

Rollback restores desired state, not necessarily data

Rules

Make Git the only durable desired-state authority/gitops/appshighstrictApply production changes through reviewed source and treat imperative cluster edits as bounded incidents that must be reconciled back.

1	Argo CD will restore declared state after a manual edit. An emergency patch that exists only in the cluster is temporary and leaves the team unable to reproduce or explain the live configuration.
2
3	- Change versioned manifests, charts, or overlays and let the reconciler apply them through the approved application boundary.
4	- If an emergency patch is required, record exact scope and expiry, apply the minimum change, then update desired state before normal reconciliation resumes.
5	- Do not configure broad ignore-difference rules to make persistent unexplained drift disappear; narrow them to known controller-owned fields.
6	- Audit direct mutation permissions and use them only for recovery paths whose actions and follow-up reconciliation are documented.
7
8	See /ops/runbooks for the adjacent decision or procedure that completes this constraint.

Enable pruning only with explicit resource ownership/gitops/platformhighstrictAssign every managed resource to one application and exclude shared or generated objects before automated deletion is allowed.

1	Pruning removes objects absent from desired state. Overlapping applications, renamed resources, generated controllers, or an incorrect source path can turn a configuration mistake into broad deletion.
2
3	- Use projects, destinations, namespaces, labels, and repository boundaries to make ownership visible and non-overlapping.
4	- Review the prune preview for rename, split, merge, and source-path changes and stage destructive transitions where rollback requires overlap.
5	- Protect persistent and shared resources with deliberate lifecycle policy rather than assuming finalizers or storage classes will save data.
6	- Apply sync windows, approvals, or manual pruning for high-blast-radius applications until ownership and recovery have been exercised.
7
8	See /gitops/apps for the adjacent decision or procedure that completes this constraint.

Memories

An Argo CD application is an ownership and blast-radius boundary/gitops/appsGroup resources that share source, destination, lifecycle, permissions, and rollback behavior rather than mirroring one giant cluster tree.

1	An application defines what reconciles and reports health together. If unrelated workloads and platform resources share one application, one invalid manifest or sync blocks and obscures everything.
2
3	- Group a service and its directly owned resources when they promote and roll back together.
4	- Separate cluster platform, shared operators, tenant infrastructure, and product workloads with projects and destinations that constrain authority.
5	- Avoid one application per tiny object when ordering and ownership are shared; the boundary should remain understandable to an operator.
6	- Use application sets for repeated, parameterized ownership across clusters or tenants without hiding generated destinations and source revisions.
7
8	See /gitops/platform for the rule or workflow that puts this decision into practice.

Sync order is a declared dependency graph/gitops/appsUse phases and waves for true readiness dependencies and keep migrations backward compatible with mixed application versions.

1	Alphabetical manifest order is not deployment semantics, and Kubernetes object creation does not imply application readiness. Database and custom-resource transitions often need explicit sequencing.
2
3	- Use pre-sync work for bounded validation or migration only when it is idempotent and reports completion clearly.
4	- Assign waves to dependencies that must become healthy before consumers progress, and define health for custom resources Argo CD cannot infer correctly.
5	- Keep schema changes compatible with old and new application revisions through rollout and rollback; a sync wave cannot make an irreversible migration safe by itself.
6	- Use post-sync checks for acceptance evidence, not for essential state the application needs to start.
7
8	See /ops/runbooks for the rule or workflow that puts this decision into practice.

Rollback restores desired state, not necessarily data/ops/runbooksReverting Git or selecting a prior revision restores manifests, while schema, external effects, and controller actions need their own recovery plan.

1	The reconciler can recreate a Deployment spec, but it cannot automatically undo data migration, issued certificate, sent message, deleted resource, or third-party change caused by the release.
2
3	- Classify every release change as declarative and reversible, declarative with retained data, migratory, or externally side-effecting.
4	- Keep prior image and configuration revisions reachable and preserve compatibility with the current data state through the rollback window.
5	- Define recovery for pruned persistent objects, migrations, secret rotations, and operator-managed resources separately from the Git revert.
6	- Verify the cluster reaches healthy prior behavior after reconciliation rather than equating a successful sync with business recovery.
7
8	See /gitops/apps for the rule or workflow that puts this decision into practice.

Skills

promote-argocd-change/rootRender, diff, sync, observe, promote, and recover an Argo CD change through explicit application boundaries.

1	---
2	name: promote-argocd-change
3	description: Promote a GitOps change across environments or clusters with Argo CD.
4	---
5
6	# Promote Argocd Change
7
8	Run this procedure when the affected surface changes, before the result is promoted to production. Record evidence for every step instead of accepting a plausible-looking result.
9
10	1. Resolve immutable artifact versions and render the exact desired manifests, then validate policy, schema, destinations, ownership, secret references, and generated output.
11	2. Inspect the Argo CD diff for replacements, pruning, immutable-field changes, shared resources, sync order, and controller-owned drift.
12	3. Sync a bounded target and watch hooks, waves, resource health, events, application signals, migrations, and custom-resource readiness.
13	4. Promote the same reviewed revision only while acceptance evidence holds and no unexplained live drift remains.
14	5. On failure, choose Git revert, prior revision, paused reconciliation, or resource-specific recovery according to data and side effects, then reconcile source and live state.
15
16	## Exit criteria
17
18	The change is complete only when the expected behavior, failure behavior, and rollback path have all been exercised with representative data. Preserve the evidence with the change so the next operator can repeat the same checks.

Why this pattern

AI agents often patch the cluster directly, enable automatic pruning before ownership is clear, hide generated drift, or order a database migration and application rollout through accidental manifest sorting.

Built for Platform teams operating Kubernetes delivery through Argo CD applications and projects.

Keeps your assistant from:

Losing an emergency cluster patch at the next reconciliation
Pruning a shared resource owned by another application
Reporting a custom resource healthy before it is usable
Deploying dependent resources in an unsafe order

View as markdown

License: Apache-2.0
Version: 1.0.0
Updated: 2026-08-25