argocd-diff-preview renders your GitOps branch before a human reads the diff

The problem is that Git shows the template, not the result

The readme states the motivation plainly. In the Kubernetes world, templating tools like Kustomize and Helm generate the manifests, which makes maintaining configuration easier across applications and environments, but also makes it harder to visualise the application's actual configuration in the cluster. Mentally parsing Helm templates and Kustomize patches is hard without rendering the actual output, so making mistakes while modifying an application's configuration is relatively easy. In GitOps, all configuration is checked into Git and modified through pull requests, and a human reviewer has to understand the changes, which is hard when the configuration is generated. The tool's answer is to render the manifests with Argo CD itself, so the diff is as accurate as possible, and it operates similarly to Atlantis for Terraform, creating a plan that outlines the proposed changes.

Ephemeral clusters by default, or a cluster you already have

There are two ways to run the render, and the readme shows both as flow diagrams. The safest way to make changes to your Helm charts and Kustomize overlays in a GitOps repository is to let Argo CD render them for you, by spinning up an ephemeral cluster or connecting to a pre-configured cluster in your automated pipelines. The ephemeral path gives complete isolation, with no access to your real cluster or Argo CD instance required. The pre-configured path connects to an install you already have, which skips cluster creation for faster execution, and the readme puts the saving at roughly 60 to 90 seconds. A third option is to run locally, so you can test changes before opening a pull request. Since the diff is rendered by Argo CD itself in all three cases, the accuracy claim does not depend on which mode you pick.

The demo runs in three commands, and the tool is a container

The readme has a tip section for trying the tool locally with three commands, and the prerequisite is that Docker is running, which you can check by running docker ps.

git clone https://github.com/dag-andersen/argocd-diff-preview base-branch --depth 1 -q
git clone https://github.com/dag-andersen/argocd-diff-preview target-branch --depth 1 -q -b helm-example-3
docker run \
   --network host \
   -v /var/run/docker.sock:/var/run/docker.sock \
   -v $(pwd)/output:/output \
   -v $(pwd)/base-branch:/base-branch \
   -v $(pwd)/target-branch:/target-branch \
   -e TARGET_BRANCH=helm-example-3 \
   -e REPO=dag-andersen/argocd-diff-preview \
   dagandersen/argocd-diff-preview:v0.2.15

The two clones give the tool a base branch and a target branch, the environment variables say which branch is the target and which repository the manifests live in, and the output directory is mounted so the result lands on your disk. The console output narrates the steps, creating a cluster, installing Argo CD, getting resources for each branch and generating the diff, and it finishes by pointing at the diff file.

The GitHub Actions workflow is a comment on every pull request

The most basic example posts the diff as a comment on the pull request, and it runs on every pull request to the main branch.

      - name: Generate Diff
        run: |
          docker run \
            --network=host \
            -v /var/run/docker.sock:/var/run/docker.sock \
            -v $(pwd)/main:/base-branch \
            -v $(pwd)/pull-request:/target-branch \
            -v $(pwd)/output:/output \
            -e TARGET_BRANCH=refs/pull/${{ github.event.number }}/merge \
            -e REPO=${{ github.repository }} \
            dagandersen/argocd-diff-preview:v0.2.15

The workflow checks out the pull request into one path and main into another, so the two branches are on disk at once, and the pull request merge ref is passed as the target branch. The job permissions are worth noting, with contents read and pull requests write, which is the minimum needed to post a comment. The comment step edits the last comment if one exists and falls back to creating a new one, so a force push updates the comment rather than filling the thread. The readme says this example works only for a public repository with public Helm charts, and that private ones need credentials supplied.

Filtering and output formats decide what the reviewer reads

The feature list is long enough to sort into what the tool does for you and what it leaves to you. It filters applications by file path, regex, labels or change detection, and it filters diff noise, ignoring version bumps, generated values and other noisy changes with a diff-ignore option, which is the difference between a usable review comment and a wall of changed image tags. It generates multiple output formats, Markdown for pull request comments, HTML and full YAML manifests, and it has a dry run mode that previews which applications would be rendered without creating a cluster. It supports private repositories and charts, multi-source applications, ApplicationSets with the List, Git and Matrix generators, and Config Management Plugins through Argo CD Helm chart configuration. The external chart case is the one to know about, since it lets you see exactly what changed when you update a Helm chart version, such as Nginx, which is a change you otherwise have to reason about from the chart's own diff.

How it finds your applications is the thing to check first

There is a constraint in the readme that determines whether the tool works for you at all. The tool will only look for YAML files in the repository with kind Application or kind ApplicationSet, and if your applications are generated from a Helm chart or a Kustomize template you have to add a step. In other words, it does not discover applications by rendering charts itself, it finds Application manifests and then lets Argo CD render them. The examples directory shows the range of situations the project expects, with directories for a basic appset, a custom target revision, a destination server, duplicate names, an external chart, a Git generator, Helm, an ignore annotation, ignore differences, an internal chart, Kustomize, label selectors, a List generator, manifest generate paths, multi-source and watch patterns. Reading those directories before wiring up a workflow is the fastest way to know which of your applications will be covered.

Where the tool is the wrong choice

The scope is narrow by design and the limits follow from the mechanism. If your repository holds plain Kubernetes YAML rather than generated templates, the diff Git already shows you is the truth, and the added value of a cluster per pull request is negative. The second limit is the cost of the run, since creating an ephemeral cluster and installing Argo CD on every pull request is minutes of compute, which is why the pre-configured cluster option exists and why the dry run mode is there. The third is that the tool renders with Argo CD, so anything Argo CD itself does not support is out of scope, and the readme's own note that applications generated from Helm or Kustomize need an extra step is the sharpest example of that. The fourth is that this is a Go program that bundles kind and Docker, and the Dockerfile copies those two binaries into a distroless image while Argo CD is installed at runtime, and the practical effect is a fairly large image and a dependency on being able to run a Docker daemon, since the socket is mounted into the container for the nested cluster.

Editorial conclusion

argocd-diff-preview suits a GitOps team whose pull requests contain Helm templates and Kustomize overlays rather than plain YAML, and it suits teams that want the review comment to show what will actually be applied to the cluster. It is the wrong tool for a repository of plain manifests, where the diff in Git is already the truth, and it is the wrong tool for an air gapped environment, since the run creates a Kubernetes cluster and talks to Argo CD. Before wiring it into a workflow, read the section on how it finds applications, because the tool only looks for YAML files with kind Application or kind ApplicationSet, and if your applications are generated from a chart you need an extra step. The last push was on 2026-10-18 and the current release is v0.2.17 from 2026-10-19.

Frequently asked questions

Official sources

1. dag-andersen/argocd-diff-preview on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases