kubechecks, seeing what a pull request will do to your ArgoCD cluster

The problem is a merge request that changes more than it shows

The project describes itself with a slogan, Fearless Kubernetes App Updates, and the one-line description is checking your Kubernetes changes before they hit the cluster.

The problem it addresses is stated in the documentation and it is specific. When using ArgoCD, it can be difficult to tell just how your Pull or Merge Request will impact your live deployment. A change to one manifest in a repo of many, applied through ArgoCD's sync, can produce a diff across the live cluster that nobody read before the merge landed.

The approach is to make the pull request itself the place where the answer appears. Every time a new PR or MR is created, kubechecks determines what is changed and how it will impact the state of the default branch, and informs you of the details directly on the PR or MR. As the documentation puts it, as a bonus it also lints and checks your Kubernetes manifests to let you know ahead of time if something is outdated, invalid, or otherwise not good practice.

That combination is the real product. A linter tells you a manifest is malformed. An impact analyser tells you what would actually change in production. Most teams have the first and lack the second, and the second is the expensive failure.

The audience is an SRE or platform team using ArgoCD with GitHub or GitLab, which is also how the project describes itself in its footer, made by the SRE team at Zapier. The last push to the repository was on 2026-10-19 and the licence is MPL-2.0, with a LICENSE file at the root.

A webhook server that clones the head SHA and comments back

The mechanism is described precisely enough in the documentation to reason about, which is not always true of tools in this space.

The tool provides a server function that processes webhooks from GitLab or GitHub, clones the repository at the HEAD SHA of the PR or MR, and runs various check suites, commenting the output of each check in a single comment on your PR or MR.

Three things follow from that sentence. First, the clone is at the head SHA, not the merge result, so the analysis is of the branch content rather than of a synthetic merge. Second, the output lands in a single comment, which matters for review ergonomics: a wall of separate comments is noise, one comment is a summary you read once. Third, the check suites run against a real clone, so they see the manifests as they will be in the repository rather than as they were when the webhook fired.

The live state comes from ArgoCD itself. The documentation states that kubechecks talks directly to ArgoCD to get the live state of your deployments and talks directly to ArgoCD's repo server to generate the new resources, so that you have the most accurate information about how your changes will affect your production code.

That second channel is the interesting one. Generating the new resources through ArgoCD's repo server, rather than rendering the manifests locally, means the comparison is between what ArgoCD would produce and what ArgoCD currently has, using the same rendering path. Any drift between your local rendering and ArgoCD's rendering, which is a common source of confusion, does not produce a false answer here.

The architecture is described as a high level structure for communicating with your VCS provider of choice, representing a PR or MR internally, and running checks for that code, with the details in the architecture document under `docs/architecture.md`.

For the dependency list, the go.mod shows a broad set of integrations. ArgoCD itself is a dependency at `github.com/argoproj/argo-cd/v3`, the GitHub clients are `github.com/google/go-github/v74` and `github.com/shurcooL/githubv4`, the GitLab client is `gitlab.com/gitlab-org/api/client-go`, and cloning is done with `github.com/go-git/go-git/v5`, so no git binary is needed on the host. The check tooling includes `github.com/open-policy-agent/conftest` and `github.com/yannh/kubeconform`, and the HTTP layer is `github.com/labstack/echo/v4`. There are also SDKs for Anthropic and OpenAI, plus AWS SDK v2 components including EKS and STS, which points to check suites that consult an external service rather than only reading manifests.

Installing it means Helm, and the chart lives in this repo

The installation section of the README is short and points at the documentation.

See [Installation Docs](https://kubechecks.readthedocs.io/en/stable/usage/)

In practice that means Helm. The repository contains a `charts/` directory, so the chart is part of the source tree rather than a separate artifact, and the install path is a Helm release pointed at your ArgoCD instance and your GitHub or GitLab installation.

That is a sensible choice for this kind of service. kubechecks is a long-running server that needs to be reachable from the Git provider's webhook side, it needs credentials for ArgoCD and for your source host, and it needs somewhere to keep whatever state it accumulates. A Helm chart expresses all of that in one declarative release, and the `kubechecks` command inside the cluster is upgradeable the same way as everything else ArgoCD manages.

The `telemetry/` directory at the top of the tree, and the OpenTelemetry packages in the go.mod, tell you that the service is instrumented and reports its own internals, which is what you want from something that sits in front of your deployment pipeline.

Two other things in the tree are worth knowing about. There is a `Dockerfile` and a separate `Dockerfile.runtime`, so the build and the runtime image are split, and the build image comment says the target binary size is 30-50MB, down from 223MB, which is a large reduction from stripping and cross-compiling rather than running an emulator. And there is a `localdev/` directory alongside a `Tiltfile` and a `.tilt/` directory, plus a `justfile` whose `start` target brings up a minikube cluster and then runs Tilt, so a developer can get a local ArgoCD and a local Git provider without hand-assembling one.

The `justfile` shows what a local run expects.

cluster_up:
	minikube start --driver=docker --addons=dashboard,ingress --cpus='4' --memory='12g' --nodes=1

That is a four CPU, twelve gigabyte minikube with the dashboard and ingress addons, which is a reasonable hint about what the local development environment costs in resources.

The Makefile documents the build, and the versions come from a file

The Makefile is where the build conventions are pinned down, and the header comment explains a migration.

The first line of the file says it is for kubechecks and that it replaces the Earthly build system with Docker Buildx and native Go tooling. That is a useful signal about the project's trajectory, because a build system migration of that size means the project has been through a period of churn in how it is built and shipped.

Versions are not hardcoded in the Makefile. They are read out of a `.tool-versions` file, which is in the repository root, using grep and awk for the Go version, the golangci-lint version and the Helm version. The same file is referenced by the Dockerfile, where the build arguments for the Go and Alpine versions say they are read from `.tool-versions`.

The image coordinates are in the Makefile too.

IMAGE_NAME ?= kubechecks
IMAGE_TAG ?= $(GIT_COMMIT)
IMAGE_REGISTRY ?= ghcr.io/zapier

# Full image reference
IMAGE_REF := $(IMAGE_REGISTRY)/$(IMAGE_NAME):$(IMAGE_TAG)
IMAGE_LATEST := $(IMAGE_REGISTRY)/$(IMAGE_NAME):latest

The default registry is ghcr.io/zapier, and the default tag is the short git commit, with a separate latest tag. The build platforms are linux/amd64 and linux/arm64.

The build itself cross-compiles rather than emulating, and the Dockerfile comment is explicit about the reason, that it avoids slow QEMU emulation. The binary is stripped with `-trimpath`, `-w` and `-s`, which is where most of the size reduction comes from.

The linting setup is golangci-lint with a `.golangci.yml` in the root, and the Makefile has a `lint` target that runs it with `--fix` across the tree. The `ci` target exists alongside `build`, `test`, `fmt` and `validate`, so the gates a pull request has to pass are declared in one place.

The local test path is minikube, Go tests and ngrok

The `justfile` is short and it documents the local development prerequisites better than the README does, because the `system_check` target checks for them explicitly.

It checks for minikube, Go and ngrok, and it fails with a count of how many checks did not pass. The ngrok requirement is the one that explains the rest of the setup, because a webhook receiver on your laptop has to be reachable by GitHub or GitLab, and ngrok is how that is arranged. The `cluster_tunnel` target runs `minikube tunnel` for the same reason, and `cluster_down` runs `minikube delete`.

The test targets are the standard Go pair.

unit_test:
	go test ./...

unit_test_race:
	go test -race ./...

The race variant exists because this is a concurrent server. It receives webhooks, clones repositories, talks to ArgoCD and renders check output, and a data race in that shape is a real possibility rather than a theoretical one.

The rest of the justfile covers the supporting tasks. `dump_crds` runs a small Go program in `tools/dump_crds/` to refresh the schemas used for checking custom resource definitions. `rebuild_docs` runs `hacks/env-to-docs.go` to regenerate documentation from environment variables, which is a pattern worth noticing: the configuration surface is large enough that the docs are generated from it rather than written by hand. `rebuild_mocks` regenerates the mocks with mockery, and there is a `.mockery.yaml` in the repository root to configure it.

The `lint` target is the same golangci-lint invocation as in the Makefile, which is a small duplication, but the justfile is the one wired into the developer loop with `start`.

So the local environment is: minikube with a dashboard and ingress, a Go toolchain, ngrok for the webhook path, and a mock-friendly test setup. That is a fair amount of infrastructure to stand up, and it is the clearest signal of what this tool costs to work on.

What ArgoCD dependency costs you

The value proposition is real, and so are the constraints, and they come from the same place: this tool reads your live ArgoCD state.

The first constraint is that ArgoCD is not optional. The impact analysis is built on talking to ArgoCD for live state and to ArgoCD's repo server for the new resources. A team that uses Flux, or plain kubectl, or a different GitOps tool gets the manifest linting and the conformance checks, which are the same checks any linter would give, and none of the impact analysis, which is the point of the tool. The repository topics list argocd, cicd and kubernetes, and the README is explicit that it is for users of GitHub and GitLab on their current ArgoCD deployments.

The second is that the tool needs broad credentials. It clones your repository, so it needs repository access. It queries ArgoCD, so it needs ArgoCD API access. It generates resources through the repo server, so it needs whatever that requires. And in a real cluster, that repository access is usually the same credential class that can push to your deployment branch, which makes the permission conversation a real one rather than a formality.

The third constraint is that the analysis is only as good as the state ArgoCD reports. If the live cluster has drifted from what ArgoCD believes, the diff you see is between ArgoCD's belief and the new resources, not between the cluster and the new resources. The tool is accurate about the thing it measures, and what it measures is what ArgoCD would sync.

There is a fourth, softer one. The check suites run on every pull request, and the go.mod includes SDKs for Anthropic and OpenAI alongside the AWS SDK, which suggests some suites call out to an external model or service. That is a deliberate feature for a team that wants an opinionated check, and it is also a data path from your pull request content to a third party that you should decide on deliberately.

The trade, stated plainly: for a team on ArgoCD, this replaces a class of surprise with a class of configuration. You gain a pull request comment that tells you the production diff, and you take on a service with credentials, a webhook endpoint, a set of check suites to agree on, and a dependency on how your ArgoCD is configured.

Editorial conclusion

kubechecks suits a team running ArgoCD on GitHub or GitLab that has been burned by a merge changing more than it looked like it would, and it suits teams that want manifest linting wired into the same pull request comment as the impact analysis. It does not suit a team that does not use ArgoCD, since the impact analysis is built on talking to ArgoCD and its repo server, and it does not suit a team that only wants a linter, since that is a smaller problem with better tools. Verify first that your ArgoCD version is one the tool supports, that the credentials you give it can reach both the ArgoCD API and the repo server, and that the conformance check suites you enable match the policy your organisation actually wants enforced on every pull request.

Frequently asked questions

Official sources

1. License: MPL-2.0
2. Project website
3. README
4. Releases
5. zapier/kubechecks on GitHub