drydock

drydock

Inspect your Argo CD fleet without getting wet.

drydock performs offline Argo CD desired-state analysis for GitOps repositories. It discovers, renders, tests, diffs, and diagnoses Applications without requiring live Argo CD or Kubernetes runtime.

It is built for operators who want to inspect rendered desired state before a change reaches the cluster. Pull request diffing is the primary workflow, but the same engine also supports render validation, image inventory, repository diagnostics, cache inspection, and embeddable Go APIs. The default workflow is a self-contained Go binary that does not need a running Kubernetes cluster, Argo CD instance, kubectl, argocd, or Helm/Kustomize CLI shellouts.

This is runtime-offline, not necessarily network-disconnected: declared Git, HTTP Helm, OCI Helm, and remote Kustomize sources may be fetched into explicit drydock caches when needed. Use --offline to require local files, repo maps, local charts, or existing cache hits only.

Install

Install from source with Go:

go install github.com/sholdee/drydock/cmd/drydock@latest

Workflows that install a released binary can use the setup action. It installs the latest release by default:

- uses: sholdee/drydock/setup-action@main

Pin a release when the workflow needs exact repeatability:

- uses: sholdee/drydock/setup-action@main
  with:
    version: v0.1.0

The setup action accepts latest, vX.Y.Z, or bare X.Y.Z and verifies the selected archive with the release checksum manifest by default.

Quick Start

Run drydock from the root of an Argo CD GitOps repository.

Test every discovered Application without printing rendered manifests:

drydock test apps --path .

Example text output:

PASS renovate
PASS cert-manager
FAIL argocd/broken Application argocd/broken source[0] path="..." ...

Compare a pull request checkout against a baseline tree:

git worktree add ../baseline main
drydock diff apps --path . --path-orig ../baseline

You can also compare against committed Git refs without creating a baseline worktree:

drydock diff apps --path . --ref-orig main
drydock diff apps --repo . --ref feature --ref-orig main

Inspect image changes in a machine-readable form:

drydock diff images --path . --path-orig ../baseline -o json

For CI jobs that have already populated drydock's source caches, require a cache-only run:

drydock test apps --path . --offline
drydock diff apps --path . --path-orig ../baseline --offline

Common Workflows

drydock <command> --help lists command-specific flags. See docs/usage.md for the full CLI guide.

What It Supports

drydock discovers and renders local Argo CD desired state, including:

• Application resources and supported ApplicationSet generators.
• Single-source and multi-source Applications.
• Directory, Kustomize, local Helm chart, remote Helm chart, and remote Kustomize sources.
• Declared Git, HTTP Helm, OCI Helm, and remote Kustomize source acquisition into local caches.
• Repository maps with --repo-map URL=PATH for adjacent local checkouts.
• Changed-only desired-vs-desired PR diffs, with strict diagnostics available when a safe ownership decision cannot be made.
• Default diff noise filtering for common Helm chart/version labels and pod-template checksum annotations, with --show-ignored-fields when those fields need inspection.
• Argo CD diff customizations such as ignoreDifferences, knownTypeFields, selected compare options, and resource filters.
• Per-Application render test status as PASS, FAIL, or SKIPPED, including structured JSON and YAML output.
• Offline validation of configured custom health Lua during render tests.
• Redacted diagnostics for settings, source repositories, AppProjects, and cache acquisition events.
• Cache lifecycle commands for Git, chart, and remote Kustomize caches.

See docs/compatibility.md for the detailed Argo CD support matrix.

Offline Runtime Model

drydock is desired-vs-desired analysis. It renders the desired Kubernetes manifests from a current tree and, for diff commands, a baseline tree. It does not ask a live cluster or Argo CD server what is currently running. Network source acquisition, when enabled, is limited to populating explicit drydock caches for declared repository, chart, and remote Kustomize inputs.

Default commands do not reproduce:

• Kubernetes API defaulting or admission mutation.
• Argo CD server-side diff.
• Live Argo CD Application health aggregation.
• Live-only managed-field ownership.
• Full Argo CD RBAC authorization.
• CLI config management plugin execution or shellout plugin adapters.

These behaviors are not silently approximated. The no-live-runtime boundary is an intentional product decision so the default cache-backed workflow stays deterministic and safe for CI.

Structured outputs keep stdout machine-parseable. Diagnostics and failure summaries are written to stderr where appropriate, and drydock avoids printing Secret values, repository credentials, tokens, SSH private keys, passphrases, registry credentials, or credential-bearing URLs.

How It Works

flowchart TD
  current[Current tree]
  baseline[Baseline tree]

  current --> discover
  baseline --> discover

  discover[Discover Argo CD Applications and settings]
  discover --> plan[Plan sources, resolve repo maps, use caches]
  plan --> render[Render desired manifests with Go libraries]
  render --> normalize[Apply Argo-aware filters and diff normalization]
  normalize --> outputs[Test statuses, manifest diffs, image diffs, diagnostics]

The render path imports Argo CD API types and selected reusable helpers, but drydock owns offline orchestration. See docs/design.md for the architecture and behavior model.

Go API

Embedding callers can use github.com/sholdee/drydock/pkg/drydock to list, render, and diff Applications without shelling out:

result, err := drydock.Render(ctx, drydock.Config{Path: "."})

drydock.NewClient accepts public Git, chart, and remote-resource acquirer interfaces, plus a public config management plugin renderer hook. Embedders can use those interfaces for tests, offline fixtures, and custom source handling. When one selected Application fails, the result still includes successful manifests, diagnostics, and per-Application statuses from the partial build.

Community

drydock is independently implemented, but its offline GitOps desired-state workflow was inspired by home-operations/flate and the home-operations community.

Join the home-operations Discord at https://discord.gg/home-operations.

Documentation

• docs/README.md: documentation ownership and routing.
• docs/usage.md: CLI examples, flags, outputs, cache behavior, and optional smoke tests.
• docs/compatibility.md: supported Argo CD behavior and intentional runtime boundaries.
• docs/release.md: release and Argo CD dependency upgrade notes.
• docs/reports/live-integration-design-gate.md: the no-live-runtime boundary decision and gate for exceptions.

License

Apache-2.0. See LICENSE.