argocd-diff
See exactly how a pull request changes the Kubernetes manifests your ArgoCD
Applications produce — no ArgoCD server, no cluster, no kubeconfig.
argocd-diff reads your Application resources from a checkout of your GitOps
repo and renders them the same way ArgoCD's repo server would. Helm charts are
pulled or read from the checkout and templated with the Helm SDK, directory
sources are used as-is, and Secret values are redacted. The only network calls
go to the chart repositories your Applications and charts point at, and
downloaded charts are cached between runs.
Give it the base and head of a pull request, and it renders both, compares
them, and produces:
- a self-contained HTML report for reviewers
- a Markdown summary to post as a PR comment

What's supported
- Helm charts from HTTP and OCI repositories
- Helm charts at a path in the repository, with their dependencies built as
helm dependency build would
- Directories of plain manifests
- Kustomizations, built with the kustomize library, with the
kustomize:
settings ArgoCD applies: namePrefix, nameSuffix, namespace,
images, commonLabels, commonAnnotations, replicas, patches and
components
- Single-source and multi-source Applications, with
$<ref>/… value files
lent by any ref source
Plugin sources aren't rendered; they're skipped with a warning. Private chart
registries work the same way they do with helm pull: log in first with
helm registry login or a Docker credential helper.
Install
Prebuilt binary: download the archive for your platform from the
releases page, check
it against checksums.txt, and put argocd-diff on your PATH.
With Go:
go install github.com/kazysgurskas/argocd-diff/cmd/argocd-diff@latest
Container image: every release is published to GitHub Container Registry
as ghcr.io/kazysgurskas/argocd-diff:<version>-amd64 and -arm64.
docker run --rm ghcr.io/kazysgurskas/argocd-diff:1.2.0-amd64 --version
GitHub Actions: use this repo as an action. See
GitHub Action.
Usage
- Check out the PR's base into
base/ and its head into head/.
- In each one, render your ArgoCD Application resources into
applications.yaml (for example, helm template on an app-of-apps chart).
- Run:
argocd-diff --summary diff.md --pr-title "$PR_TITLE" --author "$AUTHOR"
This writes the report to diff.html and the summary to diff.md.
A few things worth knowing:
- Paths:
path: and $<ref>/… value files are resolved relative to the
checkout. ArgoCD's rules decide the source type: an explicit helm:,
kustomize:, directory: or plugin: block wins, and chart: means
Helm. Otherwise the tool looks at the path: a kustomization file means
Kustomize, a Chart.yaml means Helm, and anything else is treated as
plain manifests. Plugin sources are skipped with a warning. Value files
without a $ prefix are relative to the chart. $<ref>/<file> is
relative to the root of the repository that the matching ref source
points at, which has to be the checkout. The checkout's repository is
--repo-url when given, otherwise the one the ref sources name, or the
ref: values one if they disagree. If they disagree and none is
ref: values, nothing says which repository the checkout is, so path
sources and $<ref>/ value files can't be placed: pass --repo-url.
Repositories are compared by host and path, so the HTTPS and SSH URLs of
one repository count as the same one.
Sources from a different repository than the checkout are skipped with a
warning. A ref source that also has a path is rendered, as in ArgoCD.
- Kustomize: builds use
kustomize build defaults: files can only be
loaded from inside the kustomization directory, and plugins and
helmCharts don't run. --kustomize-build-options takes the same string
as argocd-cm's kustomize.buildOptions: --enable-helm (which runs the
helm binary, or the one --helm-command names) and --load-restrictor
are honored, other flags are refused. The Application's kustomize:
settings are applied in memory, so the checkout isn't modified. A label
or annotation set in both places fails the build unless
forceCommonLabels or forceCommonAnnotations is set, as in ArgoCD.
kustomize.version is ignored with a warning, and build environment
variables such as ${ARGOCD_APP_NAME} aren't substituted;
commonAnnotationsEnvsubst only warns.
- Unrenderable sources: by default, the run fails on any source ArgoCD
would reject. That covers setting more than one source type,
chart: on
a non-Helm source, chart: on a ref source, two sources sharing a
ref, a $<ref>/ value file pointing at a ref that doesn't exist or
isn't in the checkout, a path source or $<ref>/ value file that can't
be placed because the ref sources disagree about the checkout, and a
kustomize: label or annotation that the kustomization already sets
without the force setting. Failing makes sure a broken Application
doesn't show up as "no changes". Use --skip-unrenderable to log and
skip these sources instead. Charts that fail to template, and
kustomizations that fail to build, still fail the run either way.
- Changing inputs and outputs: use
--base, --head and
--applications for the inputs, and --report and --summary for the
outputs.
- Keeping rendered manifests:
--rendered-dir saves both sides (as
base/ and head/) so other tools like kubeconform can scan them.
Otherwise they go to a temporary directory.
- Kubernetes version: there's no cluster to contact, so charts are rendered
for
--kube-version. If a chart's kubeVersion constraint rules that
version out, you'll get a clear error.
- Chart cache: charts are downloaded once into
--charts-dir and reused
afterwards. Cache this directory in CI.
$ argocd-diff --help
Render the ArgoCD Applications of two checkouts of a GitOps repository and
show what changed in the Kubernetes manifests they produce, as a
self-contained HTML report and a Markdown summary for a pull request comment.
No ArgoCD instance or cluster is needed.
By default the checkouts are ./base and ./head, each holding its Application
resources as applications.yaml; source paths in the Applications are resolved
against their checkout. Pass --no-hydrate to diff two trees that
"argocd-diff hydrate" rendered earlier.
Inside GitHub Actions the report header is filled from GITHUB_REPOSITORY,
GITHUB_BASE_REF, GITHUB_HEAD_REF and GITHUB_REF; pass --pr-title and --author
from the event.
Usage:
argocd-diff [flags]
argocd-diff [command]
Examples:
# The pull request's base is checked out in base/, its head in head/, and
# the Application resources were rendered into applications.yaml in each
argocd-diff --summary diff.md --pr-title "$PR_TITLE" --author "$AUTHOR"
# Explicit paths, keeping the rendered manifests for other tools to scan
argocd-diff --base base-checkout --head head-checkout --applications manifests/applications.yaml \
--rendered-dir rendered --report manifest-diff.html --summary manifest-diff.md
# Two trees rendered earlier with "argocd-diff hydrate"
argocd-diff --no-hydrate --base base-manifests --head head-manifests
Available Commands:
completion Generate the autocompletion script for the specified shell
help Help about any command
hydrate Render ArgoCD applications into Kubernetes manifests
Flags:
--base string Base checkout of the GitOps repository: a directory or a .zip of one (default "base")
--head string Head checkout of the GitOps repository: a directory or a .zip of one (default "head")
--applications string ArgoCD Application file inside each checkout, as "helm template" of an app-of-apps chart writes it (default "applications.yaml")
--no-hydrate Base and head are already rendered manifest trees, as "argocd-diff hydrate" writes them; diff them as they are
--kube-version string Kubernetes version to render Helm charts for (default "1.35.6")
--charts-dir string Directory pulled Helm charts are kept in between runs (default "cache")
--repo-url string URL of the repository the checkout is of, which tells $<ref>/ value files and paths from other repositories apart (default: the repository the Application's ref sources name)
--kustomize-build-options string Flags for kustomize build, as argocd-cm's kustomize.buildOptions: --enable-helm (runs the helm binary), --helm-command <binary>, --load-restrictor LoadRestrictionsNone or LoadRestrictionsRootOnly
--skip-unrenderable Skip sources ArgoCD would reject, or that can't be placed in the checkout, with a warning instead of failing; plugin sources are always skipped
--rendered-dir string Keep the rendered manifests of both sides here, as base/ and head/, for other tools to scan (default: a temporary directory)
--report string HTML report to write (default "diff.html")
--summary string Markdown summary to write, for a pull request comment (default: none)
--context int Unchanged lines the report keeps around each change (default 3)
--full-text-limit int Largest modified file, in lines, whose whole text the report embeds so context can be expanded (-1: never) (default 2000)
--title string Title of the report (default: "<repo> #<pr-number>", or the two paths)
--repo string Repository as owner/name, shown in the report header (default: $GITHUB_REPOSITORY)
--pr-number int Pull request number, shown in the report header (default: from $GITHUB_REF or $GITHUB_PR_NUMBER)
--pr-title string Pull request title, shown in the report header
--pr-url string Link from the report header to the pull request (default: github.com/<repo>/pull/<pr-number>)
--base-ref string Base branch, shown in the report header (default: $GITHUB_BASE_REF)
--head-ref string Head branch, shown in the report header (default: $GITHUB_HEAD_REF)
--author string Pull request author, shown in the report header
-h, --help help for argocd-diff
-v, --version version for argocd-diff
Use "argocd-diff [command] --help" for more information about a command.
The report
The report groups changed files by application. You get:
- unified or side-by-side view
- expandable context around each change
- filters by status, application, project, cluster and kind
- highlighting of changes within a line
- dark mode and keyboard navigation
Only
.yaml and .yml files are included.
The header shows the repo, PR, branches and author. In GitHub Actions most of
this is filled in for you:
| Flag |
Comes from |
--repo |
GITHUB_REPOSITORY |
--base-ref |
GITHUB_BASE_REF |
--head-ref |
GITHUB_HEAD_REF |
--pr-number |
GITHUB_REF on pull_request events, or GITHUB_PR_NUMBER |
So you usually only need to pass --pr-title and --author. Use --title
to override the generated title and --pr-url to override the PR link.
Labels
Each file is tagged with:
- the Application it belongs to (its
metadata.name, which is also the first
folder in the file's path)
- that Application's project (
spec.project)
- its destination cluster (
spec.destination.name)
Context
--context controls how many unchanged lines appear around each change
(default 3). --full-text-limit sets the largest file, in lines, whose full
text is embedded so you can expand context in the browser (default 2000).
Size
The diff is embedded as JSON and drawn in the browser, and only what's on
screen gets rendered. Reports with hundreds of changed manifests stay small
and fast. Secrets are already redacted before the diff is made.
Markdown summary
--summary <file> writes a short Markdown summary for a PR comment:
- a totals line, e.g. "11 manifests changed: 4 added, 6 modified, 1 deleted"
- a table with one row per application, project and cluster (collapsed if it
has more than eight rows)
If the PR doesn't change any rendered output, the summary says so in one
line.
Diffing previously rendered trees
With --no-hydrate, --base and --head are treated as trees already
written by argocd-diff hydrate, and they're compared as-is:
argocd-diff --no-hydrate --base base-manifests --head head-manifests
Project and cluster labels are read from an applications.yaml at the root
of each tree, if there is one. Without it, files are still grouped by
Application; only the project and cluster labels are left blank.
Rendering only
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 later with --no-hydrate.
Run it from inside the checkout, since source paths are relative to the
current directory.
$ argocd-diff hydrate --help
Render the ArgoCD Applications of one checkout into the Kubernetes manifests
they would deploy. No ArgoCD instance is needed.
Helm charts are pulled from their repository, or read from the checkout,
and templated. Directories of plain manifests are read as they are.
Kustomizations are built. Plugin sources are skipped with a warning. Secret
values are redacted.
Source paths in the Applications, and $<ref>/ paths in valueFiles, are
relative to the working directory, so run it from the checkout. Each
application is written to <rendered-dir>/<application>/<namespace>/<Kind>/<name>.yaml,
or to <rendered-dir>/<application>/<Kind>/<name>.yaml for a cluster-scoped
object.
Usage:
argocd-diff hydrate [flags]
Examples:
argocd-diff hydrate
argocd-diff hydrate --applications manifests/applications.yaml --rendered-dir rendered --kube-version 1.35.6
Flags:
--applications string ArgoCD Application file to render (default "applications.yaml")
--rendered-dir string Directory to write the rendered manifests to (default "rendered")
--kube-version string Kubernetes version to render Helm charts for (default "1.35.6")
--charts-dir string Directory pulled Helm charts are kept in between runs (default "cache")
--repo-url string URL of the repository the checkout is of, which tells $<ref>/ value files and paths from other repositories apart (default: the repository the Application's ref sources name)
--kustomize-build-options string Flags for kustomize build, as argocd-cm's kustomize.buildOptions: --enable-helm (runs the helm binary), --helm-command <binary>, --load-restrictor LoadRestrictionsNone or LoadRestrictionsRootOnly
--skip-unrenderable Skip sources ArgoCD would reject, or that can't be placed in the checkout, with a warning instead of failing; plugin sources are always skipped
-h, --help help for hydrate
Progress goes to stderr. On error, it prints the error once and exits with
status 1.
GitHub Action
This repo also works as a GitHub Action. It installs the release matching the
tag you reference:
- uses: actions/checkout@v4
with:
ref: ${{ github.event.pull_request.base.sha }}
path: base
- uses: actions/checkout@v4
with:
path: head
- run: |
for side in base head; do
helm template "$side" > "$side/applications.yaml"
done
- uses: kazysgurskas/argocd-diff@v1.2.0
- run: argocd-diff --summary diff.md --pr-title "$PR_TITLE" --author "$AUTHOR"
env:
PR_TITLE: ${{ github.event.pull_request.title }}
AUTHOR: ${{ github.event.pull_request.user.login }}
If you pin the action to a commit SHA, tell it which release to install:
- uses: kazysgurskas/argocd-diff@<sha> # v1.2.0
with:
version: v1.2.0
Then publish diff.html somewhere reviewers can open it (e.g. a workflow artifact
or object storage) and post diff.md as a PR comment.
For a complete example, see the workflow in
docs/gitops-workflow.md.
Smoke test
make smoke runs argocd-diff against the example in
test/smoke/ (two checkouts of a small GitOps repo) and
writes test/smoke/out/example/diff.html. To try it with your own
scenarios, see test/smoke/README.md.
Docker
docker build -t argocd-diff .
docker run -v $(pwd):/workspace -w /workspace argocd-diff --summary diff.md
License
Licensed under the Apache License.
Contributing
Contributions are welcome! Feel free to open a pull request.