# Pathrule Pattern: GitOps with Argo CD (1.0.0) # ::pathrule:package:gitops-argocd ### [RULE] Make Git the only durable desired-state authority (path: /gitops/apps) 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. - Change versioned manifests, charts, or overlays and let the reconciler apply them through the approved application boundary. - If an emergency patch is required, record exact scope and expiry, apply the minimum change, then update desired state before normal reconciliation resumes. - Do not configure broad ignore-difference rules to make persistent unexplained drift disappear; narrow them to known controller-owned fields. - Audit direct mutation permissions and use them only for recovery paths whose actions and follow-up reconciliation are documented. See /ops/runbooks for the adjacent decision or procedure that completes this constraint. --- ### [RULE] Enable pruning only with explicit resource ownership (path: /gitops/platform) 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. - Use projects, destinations, namespaces, labels, and repository boundaries to make ownership visible and non-overlapping. - Review the prune preview for rename, split, merge, and source-path changes and stage destructive transitions where rollback requires overlap. - Protect persistent and shared resources with deliberate lifecycle policy rather than assuming finalizers or storage classes will save data. - Apply sync windows, approvals, or manual pruning for high-blast-radius applications until ownership and recovery have been exercised. See /gitops/apps for the adjacent decision or procedure that completes this constraint. --- ### [MEMORY] An Argo CD application is an ownership and blast-radius boundary (path: /gitops/apps) 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. - Group a service and its directly owned resources when they promote and roll back together. - Separate cluster platform, shared operators, tenant infrastructure, and product workloads with projects and destinations that constrain authority. - Avoid one application per tiny object when ordering and ownership are shared; the boundary should remain understandable to an operator. - Use application sets for repeated, parameterized ownership across clusters or tenants without hiding generated destinations and source revisions. See /gitops/platform for the rule or workflow that puts this decision into practice. --- ### [MEMORY] Sync order is a declared dependency graph (path: /gitops/apps) 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. - Use pre-sync work for bounded validation or migration only when it is idempotent and reports completion clearly. - Assign waves to dependencies that must become healthy before consumers progress, and define health for custom resources Argo CD cannot infer correctly. - 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. - Use post-sync checks for acceptance evidence, not for essential state the application needs to start. See /ops/runbooks for the rule or workflow that puts this decision into practice. --- ### [MEMORY] Rollback restores desired state, not necessarily data (path: /ops/runbooks) 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. - Classify every release change as declarative and reversible, declarative with retained data, migratory, or externally side-effecting. - Keep prior image and configuration revisions reachable and preserve compatibility with the current data state through the rollback window. - Define recovery for pruned persistent objects, migrations, secret rotations, and operator-managed resources separately from the Git revert. - Verify the cluster reaches healthy prior behavior after reconciliation rather than equating a successful sync with business recovery. See /gitops/apps for the rule or workflow that puts this decision into practice. --- ### [SKILL] promote-argocd-change (path: /) --- name: promote-argocd-change description: Promote a GitOps change across environments or clusters with Argo CD. --- # Promote Argocd Change 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. 1. Resolve immutable artifact versions and render the exact desired manifests, then validate policy, schema, destinations, ownership, secret references, and generated output. 2. Inspect the Argo CD diff for replacements, pruning, immutable-field changes, shared resources, sync order, and controller-owned drift. 3. Sync a bounded target and watch hooks, waves, resource health, events, application signals, migrations, and custom-resource readiness. 4. Promote the same reviewed revision only while acceptance evidence holds and no unexplained live drift remains. 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. ## Exit criteria 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.