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:
- Helm charts from HTTP and OCI repositories
- Helm charts at a path in the repository, with their dependencies built as
helm dependency buildwould - Directories of plain manifests
- Kustomizations, built with the kustomize library, with the
kustomize:settings ArgoCD applies:namePrefix,nameSuffix,namespace,images,commonLabels,commonAnnotations,replicas,patchesandcomponents - Single-source and multi-source Applications, with
$<ref>/…value files lent by anyrefsource Plugin sources aren't rendered; they're skipped with a warning. Private chart registries work the same way they do withhelm pull: log in first withhelm registry loginor a Docker credential helper.
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@latestContainer 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 --versionGitHub Actions: use this repo as an action. See GitHub Action.
- Check out the PR's base into
base/and its head intohead/. - In each one, render your ArgoCD Application resources into
applications.yaml(for example,helm templateon 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 explicithelm:,kustomize:,directory:orplugin:block wins, andchart:means Helm. Otherwise the tool looks at the path: a kustomization file means Kustomize, aChart.yamlmeans 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 matchingrefsource points at, which has to be the checkout. The checkout's repository is--repo-urlwhen given, otherwise the one therefsources name, or theref: valuesone if they disagree. If they disagree and none isref: 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. Arefsource that also has apathis rendered, as in ArgoCD. - Kustomize: builds use
kustomize builddefaults: files can only be loaded from inside the kustomization directory, and plugins andhelmChartsdon't run.--kustomize-build-optionstakes the same string as argocd-cm'skustomize.buildOptions:--enable-helm(which runs thehelmbinary, or the one--helm-commandnames) and--load-restrictorare honored, other flags are refused. The Application'skustomize:settings are applied in memory, so the checkout isn't modified. A label or annotation set in both places fails the build unlessforceCommonLabelsorforceCommonAnnotationsis set, as in ArgoCD.kustomize.versionis ignored with a warning, and build environment variables such as${ARGOCD_APP_NAME}aren't substituted;commonAnnotationsEnvsubstonly 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 arefsource, two sources sharing aref, 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 therefsources disagree about the checkout, and akustomize: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-unrenderableto 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,--headand--applicationsfor the inputs, and--reportand--summaryfor the outputs. - Keeping rendered manifests:
--rendered-dirsaves both sides (asbase/andhead/) 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'skubeVersionconstraint rules that version out, you'll get a clear error. - Chart cache: charts are downloaded once into
--charts-dirand 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 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
.yamland.ymlfiles 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.
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 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).
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.
--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.
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-manifestsProject 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.
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 hydrateProgress goes to stderr. On error, it prints the error once and exits with status 1.
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.0Then 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.
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 build -t argocd-diff .
docker run -v $(pwd):/workspace -w /workspace argocd-diff --summary diff.mdLicensed under the Apache License.
Contributions are welcome! Feel free to open a pull request.

