AgentRules.org
RulesStacksClientsAuditorPrunerSelf-HealRFCsBenchmarkCLICI/CDAuthorsSubmit
This specification is maintained by the AgentRules Working Group. Have enhancements or want to claim maintainership?Submit Specification →
devopscritical PriorityID: argocd-oci-digest-ephemeral-sync-fence

ArgoCD Immutable OCI Artifact Digest Drift-Detection & Ephemeral Sync Fence

Enforces immutable OCI-packaged Helm chart deployments strictly pinned to cryptographic sha256 digests in ArgoCD Application CRDs. Prevents supply chain tampering, non-deterministic drift, and unverified mutation by establishing pre-sync ephemeral admission fences and blocking mutable semantic version tags in reconciliation loops.

Prohibited Anti-Pattern: Tracking Mutable OCI Helm Semantic Tags Without Cryptographic Digest Pinning or Ephemeral Pre-Sync Verification

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: ArgoCD Immutable OCI Artifact Digest Drift-Detection & Ephemeral Sync Fence - Enforces immutable OCI-packaged Helm chart deployments strictly pinned to cryptographic sha256 digests in ArgoCD Application CRDs. Prevents supply chain tampering, non-deterministic drift, and unverified mutation by establishing pre-sync ephemeral admission fences and blocking mutable semantic version tags in reconciliation loops.
globs: **/argo*/**/*.yaml, **/argocd/**/*.yaml, **/gitops/**/*.yaml, **/apps/**/*.yaml, **/*application*.yaml, **/*applicationset*.yaml
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/argocd-oci-digest-ephemeral-sync-fence"
---

# ArgoCD Immutable OCI Artifact Digest Drift-Detection & Ephemeral Sync Fence

> **Severity**: CRITICAL | **Category**: devops
> **Anti-Pattern Warning**: Tracking Mutable OCI Helm Semantic Tags Without Cryptographic Digest Pinning or Ephemeral Pre-Sync Verification

## System Constraints
You are a Principal Infrastructure & Security Architect enforcing zero-trust GitOps invariants for ArgoCD. Mandate that all Helm charts consumed via OCI registries explicitly define exact, immutable sha256 digest pins and utilize an ephemeral pre-sync validation fence. Never allow mutable floating tags, unpinned targetRevisions, or relaxed reconciliation policies.

## Strict Guidelines
- Engineers MUST ALWAYS pin Helm OCI targetRevision fields to an exact, immutable cryptographic sha256 digest (e.g., targetRevision: '1.4.2@sha256:7b5...').
- Engineers MUST NOT reference mutable semver tags or floating prefixes ('v1.0.0', 'latest', '^1.2.0') as the terminal ArgoCD targetRevision in production environments.
- ArgoCD Applications MUST configure 'syncPolicy.automated.prune: true' and 'syncPolicy.automated.selfHeal: true' to prevent persistent in-cluster drift.
- Deployment pipelines MUST register an ephemeral PreSync hook job or Admission Controller fence that evaluates Cosign/Notary signatures against the target OCI digest prior to resource application.
- Engineers MUST configure 'syncOptions' with 'RespectIgnoreDifferences=true' and 'ServerSideApply=true' when combined with strict digest pinning to guarantee idempotent reconciliation.
- ApplicationSet generators MUST output resolved sha256 digests sourced from an attested artifact lockfile or catalog rather than raw upstream tag strings.

## Bad vs Good Implementations
### ArgoCD Application OCI Helm Target Revision & Sync Fence

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Targeting a bare semver tag (2.4.1) allows upstream registries to overwrite the underlying image or chart layer without Git commit changes, violating immutable GitOps guarantees. Furthermore, disabling selfHeal creates silent drift if the live cluster state is modified out-of-band.
```yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: payment-processor
  namespace: argocd
spec:
  destination:
    server: https://kubernetes.default.svc
    namespace: payments
  source:
    repoURL: registry-1.docker.io/securecorp-charts
    chart: payment-service
    # ANTI-PATTERN: Mutable semver tag enables TOCTOU and supply chain poisoning attacks
    targetRevision: 2.4.1
    helm:
      releaseName: payment-processor
  syncPolicy:
    # ANTI-PATTERN: Missing selfHeal allows out-of-band cluster modifications to persist
    automated:
      prune: true
      selfHeal: false
```

#### Production Standard (Correct)
> **Standard**: The targetRevision combines the human-readable semver with an immutable cryptographic sha256 digest, guaranteeing that ArgoCD reconciles precisely the audited artifact. Self-heal and prune are enforced, eliminating live cluster drift.
```yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: payment-processor
  namespace: argocd
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  destination:
    server: https://kubernetes.default.svc
    namespace: payments
  source:
    repoURL: registry-1.docker.io/securecorp-charts
    chart: payment-service
    # COMPLIANT: Explicit immutable cryptographic digest pinned to exact OCI artifact
    targetRevision: 2.4.1@sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
    helm:
      releaseName: payment-processor
      valuesObject:
        global:
          deployedVia: argocd-digest-fence
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true
      - ServerSideApply=true
      - FailOnSharedResource=true
```

### Ephemeral PreSync Cryptographic Attestation Fence Job

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Fails to enforce an ephemeral synchronization barrier within ArgoCD's hook phase, allowing untrusted or modified charts to deploy without cryptographic attestation.
```yaml
apiVersion: batch/v1
kind: Job
metadata:
  name: manual-check
  namespace: payments
spec:
  template:
    spec:
      containers:
        - name: echo
          image: alpine:latest
          command: ["echo", "Skipping signature validation"]
```

#### Production Standard (Correct)
> **Standard**: Runs as an ephemeral ArgoCD PreSync hook that verifies the OCI chart's cryptographic signature against the cluster public key before any deployment manifests are applied. If the fence fails, synchronization aborts immediately.
```yaml
apiVersion: batch/v1
kind: Job
metadata:
  name: presync-artifact-digest-fence
  namespace: payments
  annotations:
    # COMPLIANT: ArgoCD PreSync hook blocks reconciliation until verification passes
    argocd.argoproj.io/hook: PreSync
    argocd.argoproj.io/hook-delete-policy: BeforeHookCreation,HookSucceeded
spec:
  backoffLimit: 0
  template:
    spec:
      restartPolicy: Never
      containers:
        - name: cosign-verifier
          image: gcr.io/projectsigstore/cosign:v2.2.4
          command:
            - /bin/sh
            - -c
            - |
              cosign verify \
                --key k8s://argocd/cosign-pubkey \
                registry-1.docker.io/securecorp-charts/payment-service@sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
          securityContext:
            allowPrivilegeEscalation: false
            readOnlyRootFilesystem: true
            runAsNonRoot: true
            runAsUser: 65532
```
Recommended MCP Servers (mcp-serverlist.com)

Equip agent with system tools to verify code for this stack.

Kubernetes Cluster Controller MCP
Inspects and validates ArgoCD custom resources and live cluster deployment health directly.
Recommended Agent Skills (askills.dev)

Ready-to-use executable skill functions tailored to this stack.

Sigstore Cosign CLI
Enables command-line OCI artifact signing, digest resolution, and attestation verification.
ArgoCD Official CLI
Provides declarative validation, diff evaluation, and sync-lock control for ArgoCD applications.
Architectural Specification & Invariant Rationale

Architectural Invariant Design: ArgoCD Immutable OCI Artifact Digest Drift-Detection & Ephemeral Sync Fence

ArgoCD Immutable OCI Artifact Digest Drift-Detection & Ephemeral Sync Fence defines an industrial-grade behavioral standard for devops engineering. Enforces immutable OCI-packaged Helm chart deployments strictly pinned to cryptographic sha256 digests in ArgoCD Application CRDs. Prevents supply chain tampering, non-deterministic drift, and unverified mutation by establishing pre-sync ephemeral admission fences and blocking mutable semantic version tags in reconciliation loops. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Tracking Mutable OCI Helm Semantic Tags Without Cryptographic Digest Pinning or Ephemeral Pre-Sync Verification Without an explicit system instruction file, developers spend hours debugging silent failures.
Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure ModeAI Symptom (The Anti-Pattern)SeverityProduction Impact & Remedy
AI Hallucination & Deprecation DriftTracking Mutable OCI Helm Semantic Tags Without Cryptographic Digest Pinning or Ephemeral Pre-Sync VerificationCritical
Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production.
Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture InconsistencyAI assistants produce mixed paradigms across files, creating fragmented codebase conventions.Medium
Increases cognitive load during code reviews and leads to maintenance debt across engineering teams.
Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.
Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

1

Engineers MUST ALWAYS pin Helm OCI targetRevision fields to an exact, immutable cryptographic sha256 digest (e.g., targetRevision

Engineers MUST ALWAYS pin Helm OCI targetRevision fields to an exact, immutable cryptographic sha256 digest (e.g., targetRevision: '1.4.2@sha256:7b5...').

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
2

Engineers MUST NOT reference mutable semver tags or floating prefixes ('v1.0.0', 'latest', '^1.2.0') as the terminal ArgoCD targetRevision in production environments.

Engineers MUST NOT reference mutable semver tags or floating prefixes ('v1.0.0', 'latest', '^1.2.0') as the terminal ArgoCD targetRevision in production environments.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
3

ArgoCD Applications MUST configure 'syncPolicy.automated.prune

ArgoCD Applications MUST configure 'syncPolicy.automated.prune: true' and 'syncPolicy.automated.selfHeal: true' to prevent persistent in-cluster drift.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
4

Deployment pipelines MUST register an ephemeral PreSync hook job or Admission Controller fence that evaluates Cosign/Notary signatures against the target OCI digest prior to resource application.

Deployment pipelines MUST register an ephemeral PreSync hook job or Admission Controller fence that evaluates Cosign/Notary signatures against the target OCI digest prior to resource application.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
5

Engineers MUST configure 'syncOptions' with 'RespectIgnoreDifferences=true' and 'ServerSideApply=true' when combined with strict digest pinning to guarantee idempotent reconciliation.

Engineers MUST configure 'syncOptions' with 'RespectIgnoreDifferences=true' and 'ServerSideApply=true' when combined with strict digest pinning to guarantee idempotent reconciliation.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
6

ApplicationSet generators MUST output resolved sha256 digests sourced from an attested artifact lockfile or catalog rather than raw upstream tag strings.

ApplicationSet generators MUST output resolved sha256 digests sourced from an attested artifact lockfile or catalog rather than raw upstream tag strings.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
Technical Questions & Answers

Frequently Asked Technical Questions

Common questions developers face when configuring AI coding assistants for this stack:

Q:Why is ArgoCD Immutable OCI Artifact Digest Drift-Detection & Ephemeral Sync Fence critical for AI coding assistants?

Enforces immutable OCI-packaged Helm chart deployments strictly pinned to cryptographic sha256 digests in ArgoCD Application CRDs. Prevents supply chain tampering, non-deterministic drift, and unverified mutation by establishing pre-sync ephemeral admission fences and blocking mutable semantic version tags in reconciliation loops. Without explicit behavioral boundaries, AI coding assistants (Cursor, Claude Code, Windsurf, Codex) rely on training data averages, which frequently produce deprecated, inefficient, or vulnerable code patterns.

Q:How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Tracking Mutable OCI Helm Semantic Tags Without Cryptographic Digest Pinning or Ephemeral Pre-Sync Verification) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q:Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q:Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

Open Specification · CC BY 4.0·Free for Personal, Team & Commercial In-Repo Use

Citation & Open Source Attribution Guidelines

This specification is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0). You are completely free to adapt and share this rule in your workspace. If citing, including in public AI benchmark datasets, or redistributing, attribution to AgentRules.org is required.

Related DEVOPS Rules

View all rules →
devops
86

Kubernetes Gateway API v1 HTTPRoute Canary and ReferenceGrant Invariants

Enforces strict conformance to Kubernetes Gateway API v1 specifications during migration from legacy Ingress controllers. Mandates explicit ReferenceGrant resources for cross-namespace routing, strict relative integer weighting for HTTPRoute canary releases, and explicit backendRef port declarations.

devops
118

ArgoCD ApplicationSet Matrix Generator Invariants & Cascade Deletion Guards

Enforces strict structural constraints on ArgoCD ApplicationSet Matrix generators combining cluster selectors and Git directories. Prevents catastrophic multi-cluster cascade pruning, accidental secret exposure through parameter interpolation, and runaway Application CR explosion via explicit sync policies, preservation finalizers, and parameter validation.

devops
40

Karpenter Resilient Topology, Interruption Queue, and Consolidation Budget Standard

Enforces deterministic disruption budgets, multi-instance-type diversification, and event-driven SQS interruption queue handling across Karpenter NodePools and EC2NodeClasses. Eliminates cascading eviction loops, instance starvation, and availability downtime during AWS Spot rebalances and underutilized node consolidation.

1 Rule in Stack

ArgoCD