drydock

drydock

Inspect your Argo CD fleet without getting wet

drydock is a fast, single static Go binary and embeddable library for runtime-offline Argo CD desired-state analysis. It discovers, renders, tests, diffs, and diagnoses GitOps Applications without requiring a live Argo CD instance or Kubernetes cluster.

It is built for operators who want quick, deterministic feedback before a change reaches the cluster. Pull request diffing is a key workflow, but the same native engine also supports render validation, image inventory, repository diagnostics, cache inspection, and Go API embedding.

Default commands use native Go renderers and do not shell out to kubectl, argocd, Helm CLI, Kustomize CLI, or repo-server wrappers. Runtime-offline does not mean network-disconnected: declared Git, HTTP Helm, OCI Helm, OCI artifact, and remote Kustomize sources may still be fetched into explicit drydock caches unless --offline is set.

Full documentation: sholdee.github.io/drydock.

Pull Request Review

The PR action posts a markdown summary and links a standalone Full Rendered Diff View so Argo CD/GitOps reviewers can inspect rendered Kubernetes resources before merge.

Open an example Full Rendered Diff View

Install

Install the latest Linux/macOS release with Homebrew:

brew install sholdee/tap/drydock

Homebrew installs shell completions automatically.

For GitOps repository and CI pinning, use mise with the GitHub backend:

[tools]
"github:sholdee/drydock[exe=drydock]" = "vX.Y.Z"

curl -fsSL https://raw.githubusercontent.com/sholdee/drydock/main/scripts/install-drydock.sh -o install-drydock.sh
bash install-drydock.sh --yes

curl -fsSL https://raw.githubusercontent.com/sholdee/drydock/main/scripts/install-drydock.sh | bash -s -- --yes

curl -fsSL https://raw.githubusercontent.com/sholdee/drydock/main/scripts/install-drydock.sh | bash -s -- --version vX.Y.Z --yes

- uses: sholdee/drydock/setup-action@main
  with:
    version: vX.Y.Z

name: drydock

on:
  pull_request:
    branches: [main]

permissions:
  contents: read
  pull-requests: write

jobs:
  drydock:
    runs-on: ubuntu-latest
    steps:
      - uses: sholdee/drydock/pr-action@main
        with:
          version: vX.Y.Z

docker run --rm -v "$PWD:/workspace:ro" ghcr.io/sholdee/drydock:latest test apps --path /workspace

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

Manual binary installs can generate shell completions with:

drydock completion zsh
drydock completion bash
drydock completion fish

Quick Start

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

List discovered Applications:

drydock get apps --path .

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

Diff commands use changed-only selection by default. Use --changed-only=false when you want to render and compare every discovered Application. Use repeatable --changed-only-include and --changed-only-ignore globs when CI should ignore known non-GitOps paths before changed-only ownership is evaluated.

Use repeatable --discover-ignore repository-relative globs to exclude non-deployable YAML, such as unrendered chart templates, from repository discovery before decoding. This is separate from --changed-only-ignore: discover-ignore removes files from discovery itself, while changed-only-ignore only filters changed-path selection for diffs.

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 the docs reference for the operator guide index.

What It Supports

drydock covers the common Argo CD GitOps repository shapes operators need to inspect locally and in CI:

• Application discovery: committed Applications, supported ApplicationSets, rendered app-of-apps/bootstrap children, explicit Kustomize discovery entrypoints, AppProjects, and settings objects.
• Rendering: directory, Kustomize, Helm, Jsonnet, single-source and multi-source Applications, Kustomize Helm charts, remote Helm charts, first-class OCI artifact sources (oci:// + path:), and remote Kustomize sources.
• Source acquisition: declared Git, HTTP Helm, OCI Helm, OCI artifact, and remote Kustomize inputs through explicit drydock caches, plus --repo-map for adjacent local checkouts.
• Diffs and images: desired-vs-desired manifest and image diffs, changed-only selection, default noisy-field filtering, and structured or markdown output.
• Plugins: native safe Kustomize compatibility, avp-compat placeholder redaction, ksops-compat placeholder rendering for KSOPS generators, native policy overrides, static plugin-policy init and plugin-policy doctor onboarding, trusted exec/container policy with --enable-plugins, and policy bootstrap entrypoints.
• Diagnostics: render status, custom health Lua validation, redacted settings/repository/AppProject checks, source acquisition diagnostics, and cache lifecycle commands.

See the compatibility overview for the support matrix and links to detailed reference docs.

Offline Runtime Model

drydock performs desired-vs-desired analysis. It renders Kubernetes manifests from repository inputs, explicit mappings, and drydock caches. Diff commands compare a current snapshot to a baseline snapshot.

Default commands do not ask a live Kubernetes cluster or Argo CD server what is currently running. They also do not reproduce runtime behavior such as API defaulting, admission mutation, server-side diff, live health aggregation, managed-fields ownership, or full RBAC authorization.

This boundary is intentional: normal workflows stay fast, deterministic, and safe for local use and CI. Source acquisition may still fetch declared Git, Helm, OCI, or remote Kustomize inputs unless --offline is set.

See Runtime Offline and Argo CD Render Parity for the design model and validation strategy.

How It Works

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

  current --> discover
  baseline --> discover

  discover[Discover static and rendered Argo CD fleet objects]
  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 How It Works and Argo CD Render Parity for the architecture and validation 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 inspired by Flate, a Flux resource inflator, and the home-operations community.

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

Documentation

• Documentation site: curated operator docs and full reference pages.
• Getting started: first local discovery, render test, and comparison commands.
• GitHub Actions: setup action, PR action, comments, artifacts, and caches.
• Local diffs: terminal manifest and image diff workflows.
• Compatibility: supported Argo CD behavior and intentional runtime boundaries.
• Runtime Offline: what drydock does without live Argo CD or Kubernetes.
• Argo CD Render Parity: how covered render semantics are validated against real Argo CD.
• Plugin policy: onboarding commands, trusted policy engines, schema, CMP compatibility, bootstrap discovery, and command security.
• Source acquisition: Git, Helm, remote Kustomize, cache, and auth behavior.
• Reference: operator guide index.

License

Apache-2.0. See LICENSE.