argocd-diff

module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 23, 2026 License: Apache-2.0

README

argocd-diff

argocd-diff renders ArgoCD Applications and shows what a pull request changes in the resulting Kubernetes manifests. It needs no ArgoCD server, cluster or kubeconfig. It reads Application resources from a checkout of the GitOps repository, pulls and templates Helm charts with the Helm SDK, copies directory sources as they are, and writes the manifests the way ArgoCD's repo server would, with Secret values redacted. The only network access is to the chart repositories the Applications reference, and pulled charts are cached between runs.

Given the base and head checkouts of a pull request, it renders both, diffs them, and writes a self-contained HTML report plus a Markdown summary for a pull request comment. Unlike argocd app diff, which compares the desired state against a live cluster, argocd-diff compares two versions of the desired state. That makes it usable in CI on every pull request, in repositories whose ArgoCD isn't reachable from CI, and with the rendered-manifests pattern, where the rendered tree is what gets reviewed and committed.

Supported sources are Helm charts from HTTP and OCI repositories and directories of plain manifests, in both single-source and multi-source Applications. Private chart registries work the same way as with helm pull: log in with helm registry login or a Docker credential helper first.

Usage

argocd-diff --base base-checkout --head head-checkout \
  --applications manifests/applications.yaml \
  --kube-version 1.35.6 --charts-dir charts --rendered rendered \
  --output diff.html --summary diff.md

--applications is the path, inside each checkout, of the file with the ArgoCD Application resources — for example the output of helm template on an app-of-apps chart, or a plain file of Application manifests. Source paths in those Applications (path:, $values/…) are resolved against their own checkout. Both sides are rendered and then diffed. The rendered trees are written to --rendered (replacing its base/ and head/), where other tools such as kubeconform can read them, or to a temporary directory if the flag is omitted. Since there is no cluster to ask, charts are rendered for --kube-version; a chart whose kubeVersion constraint doesn't match fails with an error saying so. Charts are downloaded once into --charts-dir and reused on later runs, so cache that directory in CI.

$ argocd-diff --help
Compare two trees of rendered manifests, as "argocd-diff hydrate" writes
them, and write a self-contained HTML report of what changed. Each input is a
directory or a zip archive of one. With --applications, each input is a
checkout of the GitOps repository (a directory or zip of one) holding that
Application file, and both are hydrated first, so one command does the whole
job.

Pull request details are optional. Inside GitHub Actions the repository, base
and head refs come from GITHUB_REPOSITORY, GITHUB_BASE_REF and GITHUB_HEAD_REF,
and the number from GITHUB_REF on pull_request events (refs/pull/<n>/merge) or
from GITHUB_PR_NUMBER if the workflow exports it, so only --base and --head are
needed there.

Usage:
  argocd-diff [flags]
  argocd-diff [command]

Examples:
  # Hydrate the base and head checkouts of a pull request and diff them
  argocd-diff --base base-checkout --head head-checkout --applications manifests/applications.yaml \
      --kube-version 1.35.6 --charts-dir charts --rendered rendered --summary diff.md

  # Or diff two trees rendered earlier with "argocd-diff hydrate"
  argocd-diff --base base-manifests --head head-manifests
  argocd-diff --base base-manifests --head head-manifests --summary diff.md
  argocd-diff --base base.zip --head head.zip --output diff.html \
      --repo hostinger/kubernetes-apps --pr-number 42 --pr-title "Bump nginx" \
      --base-ref master --head-ref feat/nginx --author alice

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  hydrate     Render ArgoCD applications into Kubernetes manifests

Flags:
      --applications string        Path, inside each tree, of the ArgoCD Application file; each tree is then a checkout of the repository, hydrated before diffing, rather than rendered manifests
      --author string              Pull request author
      --base string                Base manifest tree: a directory or a .zip (required)
      --base-applications string   ArgoCD Application resources of the base tree, for project and cluster labels (default: applications.yaml in the base tree, if present)
      --base-ref string            Base branch or ref
      --charts-dir string          With --applications, directory for storing downloaded Helm charts (default "cache")
      --context int                Unchanged lines kept around each change (default 3)
      --full-text-limit int        Largest modified file, in lines, whose full text is embedded so context can be expanded in the viewer (-1: never) (default 2000)
      --head string                Head manifest tree: a directory or a .zip (required)
      --head-applications string   ArgoCD Application resources of the head tree (default: applications.yaml in the head tree, if present)
      --head-ref string            Head branch or ref
  -h, --help                       help for argocd-diff
      --kube-version string        With --applications, Kubernetes version to use for rendering Helm charts (default "1.35.6")
      --output string              Output HTML file (default "diff.html")
      --pr-number int              Pull request number
      --pr-title string            Pull request title
      --pr-url string              Pull request URL (default: derived from --repo and --pr-number on github.com)
      --rendered string            With --applications, keep the rendered trees in this directory, replacing its base/ and head/ (default: a temporary directory)
      --repo string                Repository as owner/name
      --summary string             Also write a Markdown summary, for a pull request comment, to this file
      --title string               Report title (default: the pull request, or the input paths)
  -v, --version                    version for argocd-diff

Use "argocd-diff [command] --help" for more information about a command.

The report

The report groups files by application and offers unified and split views, context expansion, filters by status, application, project, cluster and kind, intra-line change highlighting, dark mode and keyboard navigation. Only .yaml/.yml files are included.

In GitHub Actions, --repo, --base-ref and --head-ref default to GITHUB_REPOSITORY, GITHUB_BASE_REF and GITHUB_HEAD_REF, and --pr-number is taken from GITHUB_REF on pull_request events (or from GITHUB_PR_NUMBER if your workflow exports it), so only --base and --head are required. --context sets how many unchanged lines are kept around each change (default 3) and --full-text-limit the largest modified file whose full text is embedded so context can be expanded in the viewer (default 2000 lines).

Each file is labelled with the Application it was rendered for (the first path segment, i.e. the Application's metadata.name), plus that Application's spec.project and spec.destination.name. With --applications these come from the Applications just rendered, and --base-applications/ --head-applications are not allowed. When diffing previously rendered trees, they come from applications.yaml at the root of each tree if present, or from --base-applications and --head-applications. Without either, files are still grouped by Application; only the project and cluster labels stay empty.

The diff is embedded as JSON and rendered in the browser, so a report with hundreds of changed manifests stays small and only draws what is on screen. Secrets are redacted during hydration.

--summary <file> writes a Markdown summary for a pull request comment: a totals line ("11 manifests changed: 4 added, 6 modified, 1 deleted") and a table with one row per application, project and cluster, collapsed when it has more than eight rows. A pull request with no rendered changes gets a one-line note saying so.

Rendering on its own

argocd-diff hydrate renders a single checkout into a tree of manifests. Use it for the rendered-manifests pattern, for review tools that read plain manifests, or to diff trees rendered at different times with argocd-diff --base <tree> --head <tree>.

$ argocd-diff hydrate --help
Render ArgoCD Application resources into the Kubernetes manifests they would
deploy. Helm chart sources are pulled and templated, directory sources are read
as they are, and Secret values are redacted. Each application is written to
<output>/<application>/<namespace>/<Kind>/<name>.yaml, or
<output>/<application>/<Kind>/<name>.yaml for a cluster-scoped object.

Usage:
  argocd-diff hydrate [flags]

Examples:
  argocd-diff hydrate
  argocd-diff hydrate --applications apps/applications.yaml --output rendered --kube-version 1.35.6

Flags:
      --applications string   Path to the file containing ArgoCD Application CRDs (default "manifests/applications.yaml")
      --charts-dir string     Directory for storing downloaded Helm charts (default "cache")
  -h, --help                  help for hydrate
      --kube-version string   Kubernetes version to use for rendering Helm charts (default "1.35.6")
      --output string         Output directory for the rendered manifests (default "manifests")

Progress is logged to stderr. On error, the message is printed once and the exit status is 1.

GitHub Action

This repository contains a GitHub Action. It installs the release matching the tag it is used with:

- uses: kazysgurskas/argocd-diff@v1.0.0
- run: |
    argocd-diff --base base-checkout --head head-checkout \
      --applications manifests/applications.yaml --rendered rendered \
      --output diff.html --summary diff.md

When pinning the action by commit SHA, specify the release to install:

- uses: kazysgurskas/argocd-diff@<sha> # v1.0.0
  with:
    version: v1.0.0

A typical pull request workflow checks out the base and head of the pull request into two directories, produces the Application file in each (for example with helm template on an app-of-apps chart), runs the command above, publishes diff.html somewhere reviewers can open it, and posts diff.md as a comment. None of this needs credentials for ArgoCD or the clusters, only for private chart registries.

Smoke test

make smoke runs the one-command form on the example under test/smoke/, two checkouts of a small GitOps repository, and writes test/smoke/out/example/diff.html. See test/smoke/README.md for using it with your own scenarios.

Docker

docker build -t argocd-diff .
docker run -v $(pwd):/workspace -w /workspace argocd-diff \
  --base base-checkout --head head-checkout --applications manifests/applications.yaml

License

This project is licensed under the Apache License.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Directories

Path Synopsis
cmd
argocd-diff command
internal
application
Package application reads ArgoCD Application resources and exposes the parts of them that hydration needs.
Package application reads ArgoCD Application resources and exposes the parts of them that hydration needs.
cmd
Package cmd defines the argocd-diff command line.
Package cmd defines the argocd-diff command line.
diff
Package diff compares two trees of rendered Kubernetes manifests, as argocd-diff hydrate writes them, and describes every changed file as a list of hunks with per-line metadata, ready for a report.
Package diff compares two trees of rendered Kubernetes manifests, as argocd-diff hydrate writes them, and describes every changed file as a list of hunks with per-line metadata, ready for a report.
helm
Package helm pulls charts and renders them with the Helm SDK, as `helm pull` and `helm template` would.
Package helm pulls charts and renders them with the Helm SDK, as `helm pull` and `helm template` would.
hydrate
Package hydrate renders ArgoCD Applications into the Kubernetes manifests they would deploy: Helm chart sources are pulled and templated, directory sources are read as they are, and Secret values are redacted.
Package hydrate renders ArgoCD Applications into the Kubernetes manifests they would deploy: Helm chart sources are pulled and templated, directory sources are read as they are, and Secret values are redacted.
report
Package report renders a diff.Result as a self-contained HTML page: the data is embedded as JSON and a small script builds the viewer, so a page with hundreds of changed manifests stays small and renders lazily.
Package report renders a diff.Result as a self-contained HTML page: the data is embedded as JSON and a small script builds the viewer, so a page with hundreds of changed manifests stays small and renders lazily.
version
Package version holds the build identity set by the linker (see Makefile and .goreleaser.yaml).
Package version holds the build identity set by the linker (see Makefile and .goreleaser.yaml).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL