Skip to content

Overview🔗

Argo CD Diff Preview is a tool that renders the diff between two branches in a Git repository. It is designed to render manifests generated by Argo CD, providing a clear and concise view of the changes between two branches. It operates similarly to Atlantis for Terraform, creating a plan that outlines the proposed changes.

3 Example Pull Requests:🔗

Overview🔗

The safest way to make changes to your Helm Charts and Kustomize Overlays in your GitOps repository is to let Argo CD render them for you. Since the diff is rendered by Argo CD itself, it is as accurate as possible.

The tool supports three approaches for generating previews:

Approach Best For Overhead
Ephemeral Cluster (Default) Getting started, complete isolation ~60-90s
Pre-installed Argo CD Teams prioritizing speed <10s
Pre-installed Argo CD + Self-Hosted Runner Speed + security <10s

Check out How it works

Features🔗

  • Accurate diffs - Renders manifests using Argo CD itself, so the diff is as accurate as possible
  • Complete isolation - Run with ephemeral clusters - no access to your real cluster or Argo CD instance required
  • Connect to pre-installed Argo CD - Skip cluster creation for faster execution (~60-90s saved). [Docs]
  • Run locally - Test changes before opening a pull request
  • Private repos & charts - Works with private Git repositories and Helm charts
  • Multi-source applications - Full support for Argo CD multi-source apps
  • ApplicationSets - Supports List, Git, Matrix, Merge, and other generators
  • Config Management Plugins - Use custom CMPs via Argo CD Helm chart configuration
  • External chart visibility - See exactly what changed when updating a Helm chart version (e.g., Nginx). PR example
  • Smart filtering - Filter applications by file path, regex, labels, or change detection. [Docs]
  • Diff noise filtering - Ignore version bumps, generated values, or other noisy changes with --diff-ignore
  • Multiple output formats - Generates Markdown (for PR comments), HTML, and full YAML manifests
  • Dry run mode - Preview which applications would be rendered without creating a cluster

Why do we need this?🔗

In the Kubernetes world, we often use templating tools like Kustomize and Helm to generate our Kubernetes manifests. These tools make maintaining and streamlining configuration easier across applications and environments. However, they also make it harder to visualize the application's actual configuration in the cluster.

Mentally parsing Helm templates and Kustomize patches is hard without rendering the actual output. Thus, making mistakes while modifying an application's configuration is relatively easy.

In the field of GitOps and infrastructure as code, all configurations are checked into Git and modified through PRs. The code changes in the PR are reviewed by a human, who needs to understand the changes made to the configuration. This is hard when the configuration is generated through templating tools like Kustomize and Helm.

Blog Posts🔗

Talks🔗

ArgoCon NA 2024🔗

argocd-diff-preview was presented at ArgoCon 2024 in Salt Lake City, US. The talk covered current tools and methods for visualizing code changes in GitOps workflows and introduced a new approach using ephemeral clusters to render accurate diffs directly on pull requests.

ArgoCon EU 2026🔗

argocd-diff-preview will be presented at ArgoCon EU 2026 in Amsterdam, The Netherlands. This talk shows how you can reduce preview times from minutes to seconds by connecting to a pre-configured Argo CD instance instead of spinning up ephemeral clusters. Includes real-world examples from Egmont and TangoMe.

Contributing🔗

We welcome contributions to ArgoCD Diff Preview! Whether you want to fix bugs, add new features, or improve documentation, your help is appreciated.

Please check out our contribution guidelines for details on how to set up your development environment, run tests, and submit changes.