argocd-conventions

Files (1)

• SKILL.md

SKILL.md (first lines)

# Argo CD conventions

Rules about a single Argo CD object, which hold whatever shape the repository
has.

## Repository layout: the repository's own

**Use the layout the repository already has** — its directory names, its
templating, where its values live, how it onboards a cluster and switches an
app on. Do not challenge that structure: not in a comment, not in a "this
would be cleaner as…", not by quietly adding a `lib/`. A layout is
load-bearing for people and pipelines you cannot see, and a repository that is
half one shape and half another is worse than either. If the user wants a
refactor, they will ask.

The carve-out covers layout and structure only. The rules below apply to what
you write, in the local idiom; do not sweep the repo to retrofit them. An
existing choice that breaks a rule or is a genuine correctness problem is
still said once, plainly, and proposed as its own change — then let go.

## Charts: OCI first

**Reference charts as OCI artefacts.** An OCI registry is one artefact store
for charts and images, with one credential, one mirroring story and immutable
digests — an HTTP chart repository is a second protocol, a second credential
and an `index.yaml` that gets regenerated under you.

- **Write the `repoURL` with no scheme**: `ghcr.io/<org>/charts`, never
  `oci://ghcr.io/…`. That is how Argo CD tells an OCI registry from an HTTP
  chart repository — it parses the URL and finds no host. (`oci://` is the
  `helm` CLI's form, not the `Application`'s.)
- The repository credential in Argo CD is `type: helm` with `enableOCI: true`.
- **An HTTP chart repository is a documented exception**, not a fallback:
  when upstream publishes no OCI chart at all. That reason goes beside the
  line or in `ARCHITECTURE.md` (see `architecture-conventions`); switching it
  to OCI once upstream publishes one is tracked in an issue.
- **Mirrored registries**: keep the *registry* in the cluster's values and the
  *path* beside the chart, then build the reference from the two. The path is
  a fact about the chart, the registry a fact about where the cluster can
  reach. A registry that varies per cluster and is written once per chart is
  the wrong way round.

## Chart versions: the latest, pinned exactly

Two rules that sound opposed and are not — freshness is a property of the
moment you edit the version, never a runtime behaviour.

- **Always resolve the actual latest version before writing one.** Never a
  version from memory, never "bump the patch and hope". Look it up:

  ```bash
  helm show chart oci://<registry>/<path>/<chart> | grep '^version:'
  ```

  ```bash
  helm repo add <name> <url> && helm repo update && helm search repo <name>/<chart> --versions | head
  ```

  Read the upstream release notes before bumping a major, and say in the PR
  what changed. A chart version is not a dependency bump like any other: it is
  a change to every cluster at once.
- **Pin the exact version. Never a range.** Argo CD *does* accept a semver
  constraint in `targetRevision` (`~1.2.0`, `*`), and that is precisely the
  trap: the deployed version stops being in git, two clusters synced a week
  apart run different code, and a rollback is no longer a revert. If the
  version is not in the diff, nobody reviewed it.
- **Keep "latest" true over time with a bot, not a range** — Renovate (a
  custom manager over wherever versions live, or its `argocd` manager over
  plain `Application` YAML). A bumped pin arrives as a reviewable PR, which is
  the whole difference.

## The Application

### `revisionHistoryLimit: 0`, on every Application

**Always. No exceptions, the bootstrap root app included.** Argo CD keeps the
last ten syncs in `status.history` by default, and an entry there is not a
line: it carries the fully resolved source list, chart version and revision
included. That payload grows with how often an app is synced, on an object the
ApplicationSet controller rewrites on every reconcile.

What it costs is `argocd app rollback` and `argocd app history`, and that is
the right trade: **git is the record of what was deployed**, so a rollback is
a revert and a sync. Read the commit log, not the cluster.

(The chart-level `revisionHistoryLimit` — the one that caps ReplicaSets — is a
separate knob, set in the app's values file. Same reasoning, same answer.)

### Sources

- **A `$values` ref source takes no `path`.** With one it contributes
  manifests as well as values.
- **Argo CD fails an Application whose source `path` does not exist.** For a
  directory that may be absent, point `path` at a parent that always exists
  and narrow with `directory.include`; matching nothing is legal and empty,
  missing is fatal.
- **`ignoreMissingValueFiles: true`** is what lets an optional values file be
  optional — and it hides typos in those paths, which is what a render check
  exists for.
- **`directory.include` and `exclude` globs have no path separator**: they
  match the path relative to the source's `path`, and `*` crosses `/`. So
  `*/*.yaml` matches `a/b/c.yaml` too; bound the depth with an `exclude`
  (`*/*/*` keeps only files one directory down).

### Passing values into jsonnet

One `extVar` carrying a whole config object as JSON (`{{ toJson .config }}`),
decoded as `jsonnet-conventions` says, rather than one extVar per key: the set
of goTemplate expressions that can reach a rendered Application stays small
enough to reproduce offline.

**Pass it as a plain string, never `code: true`** — `code` evaluates the value
as jsonnet, which turns a values file into an execution channel for nothing.

### Sync policy

- `CreateNamespace=true` with `managedNamespaceMetadata` for the labels other
  controllers select the namespace by. **Two Applications sharing a namespace
  must write the same metadata**, or they take turns rewriting each other's

From leroyguillaume/claude, MIT.

More from leroyguillaume/claude