DEV Community: Dag Andersen

Argo CD: Previewing Pull Request changes in SECONDS! 🥵⚡️⏰

Dag Andersen — Thu, 16 Oct 2025 15:05:49 +0000

TL;DR: You can now render previews of your PRs by using a cluster with Argo CD pre-installed instead of spinning up a new one each run. This results in very short preview times while maintaining accuracy.

This is a continuation of my first blog post: Rendering the TRUE Argo CD diff on your PRs. That article addresses a critical challenge in GitOps workflows: visualizing the actual impact of configuration changes when using templating tools like Helm and Kustomize.

The article shows how you can render changes to your manifests/Argo CD configuration directly on your pull requests using argocd-diff-preview

In short, it shows how you can transform a pull request like this:

and turn it into a preview like this:

Here are some examples:

3 Example Pull Requests:

Three Approaches to Preview Generation

Since its introduction in 2024, the tool now supports more ways of running it, so you can optimize it for your use case!

All three approaches are perfectly valid and you can choose the one that best fits your needs.

Approach 1: Ephemeral Clusters (Original)

This is the simplest solution, but also the slowest...

The original solution spins up ephemeral Kubernetes clusters inside your CI/CD pipeline, letting Argo CD itself render the manifests. This ensures maximum accuracy since the same engine that will deploy your changes generates the preview.

How it works:

Create an ephemeral Kubernetes cluster (kind, k3d, or minikube)
Install Argo CD from scratch
Apply your applications (without syncing them)
Wait for Argo CD to render the Applications in memory
Extract the manifests from the cluster
Generate the diff between the two sets of rendered manifests
Post the diff to the pull request

This is the approach described in detail in the first blog post.

Why this approach is superior to alternative tools:

True accuracy: Uses Argo CD itself rather than tools that try to mimic its rendering logic
No infrastructure access required: Can work without credentials for your production Argo CD instance
Complete isolation: Can run in complete isolation from your production systems

However, this approach has one significant limitation: Speed. Creating a cluster and installing Argo CD takes ~60 seconds every time, making even simple configuration changes take 80+ seconds to preview.

This leads us to the next approach to running argocd-diff-preview.

Trade-offs:

✅ Zero setup
✅ Complete isolation
✅ Works with any CI/CD (even works on your local machine)
❌ Slow (~60 second overhead per run)
❌ Resource-intensive (creates a new cluster for each run)

Approach 2: Cluster with Argo CD pre-installed

Instead of creating a new ephemeral cluster each time, argocd-diff-preview can now connect to a cluster with Argo CD already installed. This reduces preview times from minutes to seconds! 🤯

See it as a cluster with Argo CD pre-installed that is on standby and ready to render your manifests. Remember, the cluster only runs Argo CD and not the resources generated by the Applications. So it is fairly lightweight.

We do not recommend using your normal Argo CD instance for this. Instead, create a dedicated cluster or Argo CD instance for diff previews.

How it works:

Connect to the cluster
Apply your applications (without syncing them)
Wait for Argo CD to render the Applications in memory.
Extract the manifests from the cluster
Generate the diff between the two sets of rendered manifests
Post the diff to the pull request

Quick Demo:

# Create cluster and install Argo CD (one-time setup)
kind create cluster
helm repo add argo https://argoproj.github.io/argo-helm
helm install argo-cd argo/argo-cd --version 8.0.3 --create-namespace --namespace argocd-diff-preview

# Wait for Argo CD to be ready
kubectl wait --for=condition=ready pod -l app.kubernetes.io/name=argocd-server -n argocd-diff-preview

# Clone each branch from the PR into subfolders
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

# Run the tool (connects to the kind cluster)
docker run \
  --network host \
  -v ~/.kube:/root/.kube \
  -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.1.18 \
  --argocd-namespace=argocd-diff-preview \
  --create-cluster=false

Concurrent Runs: Multiple PRs, No Conflicts

Each run uses a unique identifier, so multiple PRs can run without collisions.

Network & Security:

The main downside here is that you need access to the Kubernetes API from your GitHub/GitLab hosted pipeline. Some organizations will see this as a no-go... which leads us to the next way of running argocd-diff-preview...

Trade-offs:

✅ Fast execution (eliminates ~60s overhead)
✅ Utilizes Argo CD caching from previous runs
❌ Infrastructure setup required (set up a cluster with Argo CD beforehand)
❌ Cluster credentials in CI/CD pipeline

Approach 3: Cluster with Argo CD pre-installed + Self-Hosted Runner

Running argocd-diff-preview on a self-hosted runner inside a cluster that has Argo CD pre-installed combines maximum performance with enhanced security. This approach eliminates both cluster creation overhead and the need to store cluster credentials in your CI/CD pipeline.

Instead of creating a temporary cluster for each diff preview, your self-hosted GitHub Actions runner connects directly to a dedicated Argo CD instance running in the same cluster as the hosted runners. This offers fast execution (no cluster creation overhead) and enhanced network and credential security.

Setup Guide:

Install Action Runner Controller (ARC) in your cluster alongside the dedicated Argo CD instance in the namespace argocd-diff-preview
The runner uses a service account to connect to the host cluster and access the Argo CD instance
The tool runs exactly as before, but without any credential management complexity and without creating an ephemeral cluster

Note: This setup is more complex than the previous two approaches. For complete setup instructions, see the self-hosted runner guide.

Trade-offs:

✅ Fast execution (eliminates ~60s overhead)
✅ Network isolation (No need to expose your cluster to the internet)
✅ No cluster credentials in CI/CD pipeline because you are using a service account from within the cluster and Argo CD already has all the credentials it needs
❌ Most complex setup (requires self-hosted runners + dedicated Argo CD)

Optimizing for Large Repositories

Even when using a cluster with Argo CD pre-installed, repositories with hundreds of applications can take 1+ minutes to render. The solution is selective rendering using annotations.

The most powerful optimization is the argocd-diff-preview/watch-pattern annotation. This tells the tool exactly which files each application cares about. An application will only be rendered if its watch patterns match any of the changed files in the PR.

Smart Application Selection

Setup Guide:

Add the argocd-diff-preview/watch-pattern annotation to your Applications and ApplicationSets
Enable automatic file change detection. Use the following flags:
1. --auto-detect-files-changed=true
2. --watch-if-no-watch-pattern-found=true

Example:

Use the argocd-diff-preview/watch-pattern annotation to tell the tool exactly which files each application cares about:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
  namespace: argocd
  annotations:
    argocd-diff-preview/watch-pattern: "apps/my-app/.*, shared/values.yaml"
spec:
  source:
    path: apps/my-app
    # ...

This application will only render if:

Any file in the apps/my-app/ directory changes
The shared/values.yaml file changes
The application's own manifest file changes (automatic)

More information about the watch-pattern annotation can be found in the application-selection documentation.

Other application selection methods:

Ignore applications: argocd-diff-preview/ignore: "true"
Filter by labels: --selector "team=frontend"
Filter by path: --file-regex="/team-a/"

Performance impact: Instead of rendering 100+ applications (60+ seconds), render only 6-10 relevant applications (~10 seconds).

For complete details, see the application-selection documentation.

Comparison: Which Approach to Choose?

Approach	Best For	Pros	Cons
Ephemeral clusters	Getting started, Full isolation	• Simple setup • Complete isolation	• Slow (~60s overhead)
Cluster with Argo CD pre-installed	Teams prioritizing speed	• Fast • Leverages Argo CD caching	• Requires dedicated Argo CD setup • Need cluster credentials in CI/CD • Infrastructure maintenance
Cluster with Argo CD pre-installed + self-hosted runner	Teams prioritizing speed AND network security	• Fast + secure • Leverages Argo CD caching • No credentials in CI/CD	• Most complex setup • Requires dedicated Argo CD and self-hosted runner setup • Infrastructure maintenance

Real-World Results

At Egmont, we use the "Cluster with Argo CD pre-installed + self-hosted runner" approach with a repository containing 600+ applications. Combined with smart application selection, we achieve preview times under 10 seconds - a 20x improvement over the original "ephemeral cluster" approach.

Each pull request preview includes a stats section at the bottom.

The key is combining two optimizations:

Use a cluster with Argo CD pre-installed to eliminate cluster creation overhead
Select only affected applications using watch patterns to minimize rendering scope

This approach maintains the accuracy that makes argocd-diff-preview superior to alternatives while delivering the preview in seconds.

Conclusion

The evolution of argocd-diff-preview proves you don't have to choose between accuracy and speed. What started as an accurate - but slow - solution has matured into a flexible tool that adapts to your team's needs - whether you prioritize simplicity, speed, or security.

Throughout this journey, one principle has remained constant: use Argo CD itself to render manifests. This ensures your previews perfectly match what will actually deploy. What's new is the speed at which this happens. By using a cluster with Argo CD pre-installed and intelligently selecting applications, we've lower preview times from minutes to seconds! ⏰⚡️

Each approach presented in this blog post has its own pros and cons. You should choose the one that best fits your needs.

I suggest that you begin with the "ephemeral cluster" approach to get familiar with the tool. As your confidence grows and speed becomes a priority, you can consider if you should switch to a faster setup using a cluster with Argo CD pre-installed. Combine this with well-placed argocd-diff-preview/watch-pattern annotations and you can achieve preview times under 10 seconds while maintaining the same accuracy you started with, even at scale.

The result? Preview rendering in under 10 seconds 🎉

For detailed setup instructions, check out:

Rendering the TRUE Argo CD diff on your PRs

Dag Andersen — Thu, 23 May 2024 10:33:41 +0000

TL;DR — The safest way to make changes to your Helm Charts and Kustomize Overlays is to let Argo CD render them for you. This can be done by spinning up an ephemeral cluster in your automated pipelines. This article presents a tool (argocd-diff-preview) for rendering manifest changes on pull requests. The rendered output is similar to what Atlantis creates for Terraform.

There’s now a PART 2 of this article with more advanced use cases: Argo CD: Previewing Pull Request changes in SECONDS! 🥵⚡️⏰

Problem

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.

If you are interested in a more detailed walkthrough for this problem, I recommend watching Nicholas Morey's talk at KubeCon 2024: "The Rendered Manifests Pattern: Reveal Your True Desired State"

This article introduces the tool argocd-diff-preview that solves this problem by rendering manifest changes directly on pull requests.

... but first, let's go through two simple examples where not rendering manifests can result in misconfiguration:

Helm misconfiguration example

Here we see an example of a developer trying to override the replica count on an Argo CD application:

This PR may look correct, but as a reviewer, you do not know if the value specified in the Helm Chart is named replicas: or replicaCount:. The code change has no effect if the value name is incorrect. Without rendering the Helm templates, the likelihood of these errors going to production is high.

Kustomize misconfiguration example

Here we see an example of a developer trying to set the replica count for both staging and production:

Again, this PR may look correct because the change happens in a base folder, so the change applies to all overlays (production and staging). But as a reviewer, you do not know if this value is overridden later down the chain of overlays.

~/someApp
├── base
│   ├── deployment.yaml        ⬅️ File changed in Pull Request
│   ├── kustomization.yaml
│   └── service.yaml
└── overlays
    ├── staging
    │   ├── cpu_count.yaml
    │   ├── kustomization.yaml
    └── production
        ├── cpu_count.yaml
        ├── kustomization.yaml
        └── replica_count.yaml ⬅️ replicaCount overwritten here

This unintended result might not have been caught without rendering the final output for staging and production.

New solution: `argocd-diff-preview`

Goal

Create a tool that works like Atlantis for Terraform but for Argo CD. The tool should render a reliable diff of the configuration changes directly on the PR. Additionally, it should work without needing access to your existing infrastructure.

Instead of creating some scripts that try to mimic how Argo CD would render the manifests, why not let Argo CD render the manifests itself? This would ensure that the rendered manifests are exactly how Argo CD would render the manifests.

How it works

argocd-diff-preview spins up a local cluster, installs Argo CD, applies the manifests to the cluster, extracts the rendered manifests from Argo CD, and compares it to the main branch.

This tool runs an ephemeral local cluster inside Docker, so it does not need access to your infrastructure. It only needs read access to the Git repository and your Helm Charts (either stored in Git or a registry)

In other words, it follows these 10 steps:

Start a local cluster
Install Argo CD
Add the required credentials (Git credentials, image pull secrets, etc.)
Fetch all Argo CD application files on your PR branch
- Point their targetRevision to the Pull Request branch
- Remove the syncPolicy from the application (to avoid the application to sync locally)
Apply the modified applications to the cluster
Let Argo CD do its magic
Extract the rendered manifests from the Argo CD server
Repeat steps 4–7 for the base branch (main branch)
Create a diff between the manifests rendered from each branch
Display the diff in the PR

The flow visualized:

Example

If you are asked for a review on a PR that looks like this:

Then you can verify that it is configured correctly by checking the output generated by argocd-diff-preview. The output would look similar to this:

Pros

Always renders the correct difference between branches because it is rendered by Argo CD itself.
Fully ephemeral cluster.
Does not access any of your existing infrastructure. It only requires read access to the Git repository and your Helm Charts.
Can be run locally before you open the pull request.
Supports multi-source applications
Supports Argo CD Config Management Plugins (CMP)
Renders changes in resources from external sources (e.g., Helm Charts). For example, when you update the Helm Chart version of nginx, you can see what exactly changed - PR example.

Cons

It is slow. Spinning up a cluster and installing Argo CD takes a few minutes each run (see table below)

Comparing desired states - Not actual state

An important point to understand is that, unlike Atlantis or the argocd diff CLI command, this approach doesn't compare the desired state in Git with the actual state in Kubernetes. Instead, it compares the desired state of the two branches stored in Git. I would argue that this is better than comparing Git with the actual state in Kubernetes because the state can change, resulting in non-deterministic output. The actual state in Kubernetes can temporarily go out-of-sync with Git, and we don't want this to be highlighted in our diff preview. Developers who work with Altanis experience this a lot - each time you run atlantis plan, it may produce a different result if the infrastructure changes often.

How to use it in GitHub Actions

Here is an example of how you would trigger argocd-diff-preview on your pull requests in GitHub Actions

name: Argo CD Diff Preview

on:
  pull_request:
    branches:
      - main

jobs:
  render-diff:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write

    steps:
      - uses: actions/checkout@v4
        with:
          path: pull-request

      - uses: actions/checkout@v4
        with:
          ref: main
          path: main

      - 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=${{ github.head_ref }} \
            -e REPO=${{ github.repository }} \
            dagandersen/argocd-diff-preview:v0.0.23

      - name: Post diff as comment
        run: |
          gh pr comment ${{ github.event.number }} --repo ${{ github.repository }} --body-file output/diff.md --edit-last || \
          gh pr comment ${{ github.event.number }} --repo ${{ github.repository }} --body-file output/diff.md
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Handling credentials

In the simple code example above, I do not provide argocd-diff-preview with any credentials, which only works if the Helm Chart registry and the Git repository are public. If you want to use this tool in a private repository, you need to provide the tool with the required credentials. More details on this can be seen in the GitHub Repository

Output

On a successful run, the tool prints the following output:

✨ Running with:
✨ - base-branch: main
✨ - target-branch: helm-example-3
✨ - repo: dag-andersen/argocd-diff-preview
✨ - timeout: 180
🚀 Creating cluster...
🚀 Cluster created successfully
🦑 Installing Argo CD...
...
🤖 Patching applications for branch: main
🤖 Patching applications for branch: helm-example-3
🌚 Getting resources for base-branch
🌚 Getting resources for target-branch
...
🔮 Generating diff between main and helm-example-3
🙏 Please check the ./output/diff.md file for differences

If something is wrong with your configuration, it prints the Argo CD Application error message:

...
🤖 Patching 4 Argo CD Application[Sets] for branch: helm-example-3
🌚 Getting resources for target-branch
⏳ Waiting for 4 out of 4 applications to become 'OutOfSync'. Retrying in 5 seconds. Timeout in 180 seconds...
❌ Failed to process application, my-app, with error:
    Failed to load target state: failed to generate manifest for source 2 of 2: rpc error: code = Unknown desc = authentication required

Speed

The table below shows how the number of applications correlates with the time it takes to render them all:

Number of applications	1	50	250	500
Seconds**	80	100	210	330

Creating a cluster and installing Argo CD on it takes around 1 minute, which is why rendering a single application takes over a minute.

**The speed can vary depending on the distribution between applications used with Kustomize, Helm, and raw manifests. This test's result is based on a codebase mainly filled with Helm Charts.

Speeding up the rendering process

Rendering the manifests generated by all applications in the repository for each pull request can be slow. The tool offers various options to limit the number of applications rendered on each PR. You can choose applications based on label selectors, file paths, or by tracking specific file changes For more information: [docs]

Conclusion

In conclusion, tackling the challenge of accurately visualizing Kubernetes configuration changes within GitOps workflows is essential for ensuring smooth operations and minimizing errors.

argocd-diff-preview works like Atlantis for Terraform. The tool lets you render the diff on PRs, making it easier to review the changes made to the configuration. Since the diff is rendered by Argo CD itself, it is as accurate as possible.

In contrast to other existing solutions, argocd-diff-preview works without direct access to your infrastructure, which can be desirable for organizations with strict security requirements.

If you experience any issues with the tool, please open an issue on the repository

DEV Community: Dag Andersen

Argo CD: Previewing Pull Request changes in SECONDS! 🥵⚡️⏰

Three Approaches to Preview Generation

Approach 1: Ephemeral Clusters (Original)

Approach 2: Cluster with Argo CD pre-installed

Approach 3: Cluster with Argo CD pre-installed + Self-Hosted Runner

Optimizing for Large Repositories

Smart Application Selection

Comparison: Which Approach to Choose?

Real-World Results

Conclusion

Rendering the TRUE Argo CD diff on your PRs

Problem

Helm misconfiguration example

Kustomize misconfiguration example

Other solutions to the problem

New solution: argocd-diff-preview

Goal

How it works

In other words, it follows these 10 steps:

Example

Pros

Cons

Comparing desired states - Not actual state

How to use it in GitHub Actions

Handling credentials

Output

Speed

Speeding up the rendering process

Conclusion

New solution: `argocd-diff-preview`