What the agent does
The agent clones the GitOps repository into its own cloud sandbox and works out how each application is rendered. In a repository like argoproj/argocd-example-apps there is no .github/ directory at all, and fifteen applications are each built a different way: guestbook/ is plain YAML with a Deployment at replicas: 1 and a Service; kustomize-guestbook/kustomization.yaml adds a kustomize- name prefix; helm-guestbook/ is a chart with replicaCount: 1 and ingress.enabled: false in values.yaml; helm-dependency/Chart.yaml pulls wordpress 9.0.3 from an upstream chart repository; jsonnet-guestbook/ and jsonnet-guestbook-tla/ are raw jsonnet, the second taking top-level arguments; sync-waves/, pre-post-sync/ and helm-hooks/ carry hook annotations; blue-green/ renders an Argo Rollouts Rollout; and plugins/kasane, plugins/kustomized-helm and plugins/nix need a config management plugin sidecar that only exists inside Argo CD. apps/ is the app of apps: a chart whose values.yaml lists every application with its path, tool and destination, and whose templates/applications.yaml renders one Application named example.<name> with automated sync, prune and self-heal.
It writes a render script, hack/render.sh, that takes an application directory and an output file and picks the tool from what is in the directory: kubectl kustomize when there is a kustomization.yaml, helm dependency build followed by helm template with the release name the apps/values.yaml entry gives when there is a Chart.yaml, jsonnet for .jsonnet files with the --tla-str defaults the Application would pass, and a concatenation of the YAML files otherwise. Directories under plugins/ are listed as not renderable outside Argo CD and skipped with a line saying so. Rendering apps/ itself through helm template means a change to values.yaml shows up as a diff in Application objects, which is the change most likely to surprise someone.
Then it adds .github/workflows/manifest-diff.yml on pull_request, with permissions of contents: read and pull-requests: write, a checkout at fetch-depth: 0, pinned installs of kubectl, helm and jsonnet, and a job that lists the application directories the pull request touches, renders each at the merge base through a git worktree and at the head, runs diff -u on the two outputs, and posts one comment through gh pr comment, updating the same comment on later pushes rather than adding another, with each application's diff in a collapsed section and a note for any directory it could not render. An optional second step, guarded by the presence of ARGOCD_SERVER and ARGOCD_AUTH_TOKEN secrets, runs argocd app diff example.<name> --local <dir> --server-side-generate so a team with a reachable Argo CD gets the diff against the live cluster state rather than against the base branch.
It proves the pipeline on every application before it opens anything. In the sandbox it installs the three tools, renders all fifteen directories at HEAD and records which ones render, which are plugin apps, and whether helm-dependency can fetch its upstream chart; then it makes a throwaway change, bumping replicas in guestbook/guestbook-ui-deployment.yaml, and runs the script end to end to show the exact comment body the workflow would post. It runs actionlint on the workflow and shellcheck on the script, discards the throwaway change, and pastes the outputs into the pull request description.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add a rendered manifest diff to every pull request in this Argo CD repository. Read the README, the app-of-apps chart and its values, and every application directory first, and classify each by how it renders: plain YAML, kustomize, helm, jsonnet, or a config management plugin. Write hack/render.sh that renders one application directory with the right tool, using release names and top-level arguments from the Application definitions, and reports plugin apps as not renderable outside Argo CD. Add a pull_request workflow with read contents and write pull-requests permissions that finds the application directories the pull request changes, renders each at the merge base and at the head, diffs them, and posts or updates one collapsed-per-app comment with gh. Add an optional argocd app diff step that runs only when ARGOCD_SERVER and ARGOCD_AUTH_TOKEN secrets exist. In your sandbox install the tools, render every application at HEAD and record the result, make a throwaway change to one app to show the comment the workflow would post, run actionlint and shellcheck, discard the throwaway change, and open a pull request with the classification table and the command output.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
What comes back is a pull request adding hack/render.sh and .github/workflows/manifest-diff.yml, and nothing under the application directories. The description holds a table of every application with its render tool and whether it rendered in the sandbox, the plugin apps marked as skipped with the reason, and the sample comment the throwaway replicas change produced, so a reviewer sees the output format before the workflow ever runs.
The run's record keeps the render of all fifteen directories, the diff from the throwaway change, and the actionlint and shellcheck output, which is how a reviewer knows the script handles the kustomize prefix, the helm release names and the jsonnet arguments without running it.
Before merging, a reviewer decides whether the optional argocd app diff step is worth a read-only Argo CD token in repository secrets, whether comments should also be posted for pull requests that change only apps/values.yaml, and whether a diff on Application objects should block merge through a required check or stay informational.
Run it on every pull request
Once the workflow is merged, every pull request carries its rendered diff. The recurring agent work sits on top of it: a team starts one run per pull request from an automation with a github trigger on pull_request.opened and pull_request.synchronize, in the Project that holds the GitOps repository, with a prompt asking the agent to read the rendered diff, explain in plain words what will change in the cluster after sync, and flag a change that prunes a resource, alters a hook or sync wave, or touches an Application destination.
The trigger adds the pull request after the prompt. Each run checks out that branch in its own sandbox, renders the applications itself so its reading does not depend on the comment, and posts one review. Only work by an owner, member or collaborator fires the trigger; a pull request from a fork never does, and an automation run has its own max_runs_per_hour cap.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A GitOps repository that mixes plain YAML, kustomize, helm, jsonnet and plugins has no single render command, and writing one means trying it against every application. The sandbox has the tools installed in minutes and every directory to try them on, so the script that reaches the pull request has already rendered the whole repository once, and the one case it cannot handle, plugin apps, is named rather than discovered later in a failed workflow run.
The same body runs against every Argo CD repository an organisation keeps, each with its own mix of tools and its own app of apps, and each run leaves the full render record with the pull request. A platform team compares the classification tables and gets one diff comment format across all of them.
Frequently asked questions
Does this need access to our Argo CD server?
No. The default diff renders the base and head of the pull request with the same tools Argo CD uses and compares them, which needs only the repository. The argocd app diff --local step is optional and runs only when the two secrets exist, for teams that want the comparison against what is actually in the cluster.
What about apps that use a config management plugin?
They are listed in the comment as not rendered, with the plugin name. A plugin runs as a sidecar inside the Argo CD repo server, so reproducing it in a workflow means re-implementing the plugin. Teams with a plugin app usually render it through the optional argocd app diff step instead.
Will the helm-dependency app render in CI?
Only if the upstream chart repository is reachable from the runner, since helm dependency build fetches wordpress 9.0.3 before helm template. The sandbox run records whether that fetch worked, and the script treats a failed fetch as a reported error for that one app rather than a failed job.
Does a diff on the app-of-apps show as Application changes?
Yes. apps/ is rendered through helm template like any chart, so editing apps/values.yaml produces a diff in the Application objects, including a changed path, targetRevision or destination namespace, which is the kind of change worth reading twice before an automated sync picks it up.
Will it post a new comment on every push?
No. The workflow looks for its own earlier comment by a marker line and edits it, so a pull request carries one diff comment that always reflects the latest commit.
More Argo CD jobs
More jobs like this: Hand off a long task
- Add LaTeX Math Rendering to an Astro Blog (Astro)
- Add the Maven Wrapper to a Maven Project (Maven)
- Make GitHub Actions Workflows Run in a Merge Queue (GitHub Actions)