KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #typescript #developer-tools #claude-code #ai-agent #codex #deepseek-harness #ai-agents #cli #react #mcp

argo-diff

★ 57 Open GitHub ↗

Go application that provides Github Pull Request comments to preview live Kubernetes manifest changes managed by ArgoCD

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Argo-Diff

An application written in [go](https://go.dev/) that provides Pull Request comments for changes to
Kubernetes manifests when those manifests are delivered via [ArgoCD](https://argo-cd.readthedocs.io/en/stable/):

## Contents

- [Overview](#overview)
  - [Why argo-diff?](#why-argo-diff)
  - [Screenshots](#screenshots)
- [Deploying as a Webhook receiver](#deploying-as-a-webhook-receiver)
- [GitHub Actions](#github-actions)
- [Configuration](#configuration)
- [Running locally](#running-locally)
- [Development Notes](#development-notes)

## Overview

Argo-diff is designed to receive webhook notifications from GitHub for `pull_request` and `issue_comment`
events. When events are received, it uses the ArgoCD CLI to identify the ArgoCD application(s) that are
configured with the pull request's repository as a source and to generate a diff of those applications
against the live state.

Argo-diff will comment on the associated pull request with markdown displaying the diffs for the applications
with potential changes.

Argo-diff will **not** run when the base branch of the pull request (the branch it will be merged into) is
not the target revision for the Argo application. (eg: your Argo application targets `production`, but your
PR is to be merged into `dev`.)

### Why argo-diff?

There are multiple ways to produce diff previews of proposed manifest changes to ArgoCD applications in GitHub
Pull Requests, but they often require per-repository configuration. Because argo-diff is triggered by GitHub
event notifications, and because argo-diff auto-discovers ArgoCD applications configured in the source code
repository, no configuration is needed when repositories and/or ArgoCD applications are added and removed.

Argo-diff natively supports ArgoCD's
[`manifest-generate-paths`](https://argo-cd.readthedocs.io/en/stable/operator-manual/high_availability/#manifest-paths-annotation)
annotation. This annotation is useful for monorepos that contain the manifests for many ArgoCD applications.
For applications with it set, ArgoCD will only attempt to produce diffs for the applications whose
`manifest-generate-paths` match the pull request's files changed (which is fetched via the GitHub API).

Argo-diff supports multi-source ArgoCD applications, including helm applications whose Application specs
are managed by ArgoCD. This means if, in source control, you have a pull request that updates the chart
version in the Application spec of a helm application, argo-diff will produce a diff of the affected
application.

Argo-diff can also be quickly deployed via GitHub Actions.

### Screenshots

Below are screenshots of GitHub Pull Request comments generated by argo-diff.

#### Simple comment of healthy application
<img src="./docs/img/diff-comment-00.png?raw=true" width="456" />

#### Long line in diff truncated
<img src="./docs/img/diff-comment-01-long-line.png?raw=true" width="449" />

#### Application out of sync
<img src="./docs/img/diff-comment-02-app-out-of-sync.png?raw=true" width="462" />

#### Helm application (argo-diff via GitHub Actions)
<img src="./docs/img/diff-comment-03-helm-application.png?raw=true" width="464" />

## Deploying as a Webhook receiver

Deploying argo-diff as a long-running webhook receiver takes five steps: grant it access to the GitHub
API, create a read-only ArgoCD user, generate a shared webhook secret, deploy it to Kubernetes, and point
GitHub webhooks at it.

### 1. Grant access to the GitHub API

Access can be granted either via a Personal Access Token (good for small environments or a proof of
concept) or a GitHub App.

**Option A — Personal Access Token (PAT)**

- It is recommended to create a separate GitHub account in your organization specifically for argo-diff.
- argo-diff looks for the PAT in the `GITHUB_TOKEN` or `GITHUB_PERSONAL_ACCESS_TOKEN` env var.
- The PAT's permissions should match the GitHub App permissions listed below.

**Option B — GitHub App**

Create a new application in your organization under **Developer Settings**:

- Name can be `argo-diff`.
- Homepage URL can be the base URL of your ArgoCD instance or of your webhook URL.
- Callback URL and Setup URL should be empty.
- Webhooks should **not** be active.
- **Permissions**:
  - **Administration**: `Read-only`
  - **Commit statuses**: `Read and write`
  - **Metadata**: `Read-only`
  - **Pull requests**: `Read and write`
- _Where can this GitHub App be installed?_ → `Only on this account`
- After creating the App, note the `App ID`, then generate a new Private Key (this downloads a `.pem`
  file locally).
- Install the App to your organization. The installation settings URL looks like
  `/organizations/<ORG_NAME>/settings/installations/<INSTALLATION_ID>` — note the installation id from it.
- argo-diff reads the App configuration from the `GITHUB_APP_ID`, `GITHUB_APP_INSTALLATION_ID`, and
  `GITHUB_APP_PRIVATE_KEY` env vars (the last being the contents of the `.pem` file above).

### 2. Create an ArgoCD user

Create a user in your ArgoCD instance with read-only access to all applications.

- If you installed ArgoCD from its Helm chart, add an argo-diff user via the chart's values:
  ```yaml
  configs:
    cm:
      accounts.argodiff: apiKey
      accounts.argodiff.enabled: "true"
  ```
- In _policy.csv_: `g, argodiff, role:ci` and `p, role:ci, applications, get, *, allow`. (This may not
  be needed if users in your ArgoCD installation default to the `role:readonly` role.)
- This user doesn't need a password but does need an API token, which an admin can generate via the UI
  or CLI. Use the generated token as the value of `ARGOCD_AUTH_TOKEN`.

### 3. Generate a webhook secret

Generate a webhook secret that is shared by both the argo-diff deployment and the GitHub webhook
configuration.

### 4. Deploy to Kubernetes

- **Recommended:** use the Helm chart in [charts/argo-diff/](charts/argo-diff/):
  ```console
  helm install my-release oci://ghcr.io/vince-riv/chart/argo-diff
  ```
  To run an argocd CLI version other than the one baked into the argo-diff image, set the chart's
  `argocdCli.image.tag` value — see [charts/argo-diff/README.md](charts/argo-diff/README.md#values).
- Alternatively, use the example manifests in [docs/k8s/](docs/k8s/) to deploy argo-diff to the argocd
  namespace of your cluster. You'll need to add an Ingress or IngressRoute so GitHub can reach the
  `/webhook` endpoint on the argo-diff Service.

### 5. Configure GitHub webhooks

Configure organization-level (or repository-level) webhook notifications to argo-diff. The Payload URL
should map to the ingress configured in your cluster, and the secret should be the webhook secret
generated above. Enable these event types:

- **Issue comments** — lets a comment of `argo diff` re-trigger argo-diff on the pull request.
- **Pull requests**

> **Note:** argo-diff only supports pull request events. Push events to branches are ignored.

After the webhook is activated, argo-diff should receive and verify the ping event, confirming
connectivity from GitHub to argo-diff.

## GitHub Actions

argo-diff can also run as a GitHub Action. This requires that your ArgoCD instance be reachable from the
GitHub Actions runner — either ArgoCD is publicly available (and you accept the associated risks) or you
use self-hosted runners within your environment.

The upside is that neither a GitHub account nor a GitHub App needs to be provisioned; you only need an
ArgoCD user for argo-diff:

- Create a read-only ArgoCD user as described in [step 2 above](#2-create-an-argocd-user).
- Save its API token to the repository's Actions secrets and pass it to the `argocd_auth_token` input.

The downside is that GitHub workflows are typically managed on a repo-by-repo basis, and performance is
a little slower than the deployed version.

Here's an example workflow snippet, assuming a self-hosted runner and that an ArgoCD auth token has been
added to the repository's secrets:

```yaml
---

on:
  pull_request:
    branches: [main]

permissions:
  pull-requests: write

jobs:
  argo-diff:
    runs-on: [self-hosted]  # remove when running on GitHub's public runners and ArgoCD is publicly available
    name: Argo Diff
    steps:
      - name: ArgoCD Diff
        id: argo-diff
        uses: vince-riv/argo-diff@v2  # or pin an exact release, e.g. @2.10.0
        with:
          argocd_auth_token: ${{ secrets.ARGOCD_AUTH_TOKEN }}
          argocd_server: argocd-server.argocd.svc.cluster.local:80  # argocd.domain.example when publicly available via https
          argocd_server_insecure: true                              # typically false when publicly available via https
          argocd_server_plaintext: true                             # typically false when publicly available via https
          argocd_ui_base_url: https://argocd.domain.example
          argocd_grpc_web: true
          github_token: ${{ secrets.GITHUB_TOKEN }}
          log_level: trace
          repo_default_ref: main
```

> **Note:** Releases were previously published under an `actions-vX.Y.Z` tag prefix (with a floating
> `actions-vX` major tag). Those tags are still maintained alongside the plain `vX`/`X.Y.Z` tags shown
> above for existing consumers, but new workflows should prefer the plain tags.

## Configuration

When deployed as a web service, argo-diff accepts all configuration options via environment variables.
When used via GitHub Actions, the relevant options are accepted via inputs. The following table describes
the accepted environment variables and their respective GitHub Actions inputs.

> **Important:** Valid GitHub API credentials are required to run — either the `GITHUB_APP_*` variables
> must be set, or `GITHUB_TOKEN` / `GITHUB_PERSONAL_ACCESS_TOKEN` must be set.

| Environment Variable             | Input Name                  | Required         | Default  | Description |
| -------------------------------- | --------------------------- | ---------------- | -------- | ----------- |
| APP_ENV                          | N/A                         | no               |          | Set to `dev` during local development. |
| ARGOCD_AUTH_TOKEN                | argocd_auth_token           | yes              |          | Bearer token for ArgoCD (value passed to `--auth-token`). |
| ARGOCD_APP_DIFF_SERVER_SIDE_DIFF | argocd_app_server_side_diff | no               |          | Set `--server-side-diff` for `argocd app diff` (`true`/`false`). |
| ARGOCD_CLI_CMD_NAME              | N/A                         | no               | `argocd` | Overrides the `argocd` CLI command name (e.g., to use a specific argocd version); accepts either a bare command name on `PATH` or an absolute path to the binary. |
| ARGOCD_GRPC_WEB                  | argocd_grpc_web             | no               | `false`  | Set `--grpc-web` flag for argocd cli (`true`/`false`). |
| ARGOCD_GRPC_WEB_ROOT_PATH        | argocd_grpc_web_root_path   | no               |          | Value for `--grpc-web-root-path` for argocd cli. |
| ARGOCD_OPTS                      | argocd_opts                 | no               |          | Additional flags for argocd cli. |
| ARGOCD_SERVER_ADDR               | argocd_server               | yes              |          | ArgoCD server name (value passed to `--server`). |
| ARGOCD_SERVER_INSECURE           | argocd_server_insecure      | no               | `false`  | Set `--insecure` flag for argocd cli (`true`/`false`). |
| ARGOCD_SERVER_PLAINTEXT          | argocd_server_plaintext     | no               | `false`  | Set `--plaintext` flag for argocd cli (`true`/`false`). |
| ARGOCD_UI_BASE_URL               | argocd_ui_base_url          | no               |          | Base URL of ArgoCD UI (usually the server name prefixed with `https://`). |
| ARGO_DIFF_COMMENT_PREAMBLE       | comment_preamble            | no               |          | String/markdown prefixed to comments. Keep to 150 chars or less. |
| ARGO_DIFF_CONTEXT_STR            | context_str                 | no               |          | Unique identifier of the argo-diff instance. Use when deploying multiple instances (eg: one per cluster); a brief cluster nickname is recommended. |
| ARGO_DIFF_DISABLE_NON_GITHUB_REPO_MATCH | N/A                   | no               | `false`  | Set to `true` to disable matching ArgoCD application sources on non-`github.com` git hosts (GitHub Enterprise, AWS CodeConnections, GitLab, mirrors, etc.) by `owner/repo` path suffix; matching on `github.com` URLs is unaffected. |
| ARGO_DIFF_TIMEOUT                | timeout                     | no               | `3m`     | How long argo-diff may spend generating diffs for a single event, as a Go duration (eg: `5m`, `90s`); a bare integer is treated as seconds. Raise this when a change matches many ArgoCD applications, since each one costs a round trip to the argocd server. Reporting results to GitHub gets up to 30 seconds on top of this, so a run can take that much longer than the value set here. Any applications left undiffed when the time runs out are named in a warning in the PR comment, and the run is failed — a failed step under GitHub Actions (commit statuses are skipped there), or a `failure` commit status when deployed as a service. |
| COMMENT_LINE_MAX_CHARS           | comment_line_max_chars      | no               | `175`    | Individual lines in argo-diff PR comments longer than this are truncated. |
| GITHUB_APP_ID                    | N/A                         | no               |          | GitHub Application Id (see deployment instructions). |
| GITHUB_APP_INSTALLATION_ID       | N/A                         | no               |          | GitHub Application Installation Id (see deployment instructions). |
| GITHUB_APP_PRIVATE_KEY           | N/A                         | no               |          | GitHub Application Private Key (see deployment instructions). |
| GITHUB_PERSONAL_ACCESS_TOKEN     | N/A                         | no               |          | Bearer token for GitHub API calls; same as `GITHUB_TOKEN`. |
| GITHUB_TOKEN                     | github_token                | yes for GHA      |          | Bearer token for GitHub API calls (in a GitHub Actions workflow, usually `secrets.GITHUB_TOKEN`). Required in GitHub Actions. |
| GITHUB_WEBHOOK_SECRET            | N/A                         | yes for deployed |          | Shared secret for GitHub webhook validation. Required when deployed. |
| LOG_LEVEL                        | log_level                   | no               | `info`   | Log level of argo-diff. |
| REPO_DEFAULT_REF                 | repo_default_ref            | no               |          | Default branch of the repository (eg: `main`). Only needed in GitHub Actions when `HEAD` is specified as the target revision in the ArgoCD application source. |

> **Note:** When running via GitHub Actions, argo-diff uses the following environment variables set by
> GitHub: `GITHUB_ACTIONS`, `GITHUB_BASE_REF`, `GITHUB_EVENT_NAME`, `GITHUB_HEAD_REF`, `GITHUB_REF`, and
> `GITHUB_REPOSITORY`. Do not set these yourself.

## Running locally

Set the environment variables used by argo-diff and then execute `go run cmd/main.go`.

For example, you can place these in a file called `.env.sh`:

```sh
GITHUB_PERSONAL_ACCESS_TOKEN='github_pat_XXXX'
ARGOCD_AUTH_TOKEN='ABCDEFGHIJKLMNOPQRSTUVWXYZ'
ARGOCD_SERVER_ADDR='argocd.your.domain:443'
ARGOCD_UI_BASE_URL='https://argocd.your.domain'
APP_ENV='dev'
```

Then source it and start the server:

```console
$ set -o allexport ; . .env.sh ; set +o allexport
$ go run cmd/main.go
```

Or run it once to process a manually crafted event file:

```console
$ set -o allexport ; . .env.sh ; set +o allexport
$ go run cmd/main.go -f path/to/event_info.json
```

> **Note:** argo-diff shells out to the `argocd` CLI, so a compatible `argocd` binary must be on your
> `PATH` (override the command name, or point at an absolute path, with `ARGOCD_CLI_CMD_NAME`).

### Craft a local file with event data

When running locally, the easiest way to trigger argo-diff is to create a JSON file that can be
unmarshalled into an `EventInfo` struct (defined in `internal/webhook/process.go`):

```json
{
    "ignore": false,
    "owner": "GITHUB_ORG_NAME",
    "repo": "REPOSITORY_NAME",
    "default_ref": "main",
    "commit_sha": "LONG_SHA_OF_COMMIT",
    "pr": 123,
    "change_ref": "BRANCH_NAME_OF_PR",
    "base_ref": "main"
}
```

Description of those fields:

- `ignore`: tells argo-diff to ignore the event
- `owner`: GitHub organization name
- `repo`: GitHub repository name
- `default_ref`: the default branch of the repository
- `commit_sha`: the sha that triggered the event — should be HEAD of the branch of the PR if you want it to comment
- `pr`: pull request number (duh)
- `change_ref`: the source branch of the PR (the feature branch)
- `base_ref`: the branch to which the PR is getting merged

This JSON file can be passed to argo-diff via the `-f` argument or posted to the `/dev` HTTP endpoint.

### Testing HTTP endpoints locally

To simulate GitHub webhook requests, copy the webhook request headers and payload to
`temp/curl-headers.txt` and `temp/curl-payload.json`, then use the `post-local.sh` script to ship them
to the local server.

There is also a `/dev` endpoint that is enabled when `APP_ENV=dev`. It is handled by `devHandler()` in
`internal/server/http_server.go`; it bypasses webhook signature validation and triggers argo-diff for
the posted event.

When `APP_ENV` is `dev`, argo-diff will comment but will not set commit status checks.

## Development Notes

This was originally developed by @vrivellino as a way to learn Go. Its functionality replicates that of an
internal tool written by smart people at a previous job.

argo-diff

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README