# Argo CD Image Updater writes parameter overrides, not manifests

> Argo CD Image Updater watches registries for new tags on images used by Argo CD Applications and then rewrites the version, either through the Argo CD API or by committing parameter overrides to Git. It only works for Kustomize, Helm and Config Management Plugin applications, and the project itself does not recommend it for critical production workloads.

**argoproj-labs/argocd-image-updater** — Automatic container image update for Argo CD

- Repository: https://github.com/argoproj-labs/argocd-image-updater
- Website: https://argocd-image-updater.readthedocs.io/en/stable/
- Stars: 1,728 · Forks: 385
- Language: Go
- License: Apache-2.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/argoproj-labs-argocd-image-updater

## The updater never edits your manifests

Most tools in this space rewrite the image line in a deployment manifest and commit that. This one deliberately does not. The README states that it writes Parameter Overrides, and calls the approach a compromise between having everything in Git and minimizing conflicts. That single design choice explains both the appeal and the friction.

The appeal is reviewability. A diff that shows one override field changing is small enough to eyeball, and it does not collide with a human editing the same manifest. The friction is that Argo CD has to support override storage in whichever system you chose, and that a team reading only the repository has to know overrides are where the real image version lives.

Support for writing to Git arrived in v0.9.0 and requires Argo CD v1.9.0 or later. The alternative path, the Argo CD API, works for Applications that are not in Git at all.

## An ImageUpdater CR holds the tracking rules

Configuration is a dedicated ImageUpdater custom resource, one per image you want followed. It declares which Argo CD Application to act on, which image to watch, and how to select a tag. The controller then polls the registry, and when a newer tag matching the rules appears it updates the Application.

The dependency list in go.mod shows where the registry side of that comes from. There is a vendored registry-scanner module, github.com/argoproj-labs/argocd-image-updater/registry-scanner v1.3.0, built on distribution v3.1.2 and using opencontainers/go-digest for content addressing. The module file also carries a maintenance note: when the vendored distribution copy is refreshed, the import paths under registry-scanner/pkg/registry/internal/ have to be reverted manually afterwards. That is a sign of how much internal API surface this project is carrying.

Credentials are handled per registry, and the presence of skeema/knownhosts and ghinstallation in the dependency list indicates host key and GitHub App style authentication paths rather than a single hardcoded credential model.

## Kustomize, Helm and Plugins only, and that boundary is not going away

The hard limitation is stated in the introduction and repeated in the FAQ: only Applications built with Kustomize, Helm or a Config Management Plugin are supported, and Applications built from plain YAML are not supported and, in the project's own phrasing, may never be. Further expansion depends on what functionality Argo CD itself exposes.

That constraint should drive the adoption decision. If your platform repository is mostly raw YAML, this tool does nothing for you and no amount of configuration changes it. The roadmap checkbox for extending to other application types is still open.

Permanent integration into Argo CD is also not on the table. The README says that in its current form this is probably not going to happen, and points at an open proposal in argoproj/argo-cd to migrate the project from the argoproj-labs org into argoproj and ship it with Argo CD itself. Until that proposal resolves, you are deploying a sidecar controller with its own release cycle.

## The runtime image ships git, ssh, gpg and aws-cli

The Dockerfile explains what the controller needs at runtime. The build stage uses golang:1.26 and runs make build, matching the go.mod requirement of 1.26.3. The final stage is alpine:3.24, and the package list is longer than you would expect for a controller that mostly edits text:

Those packages follow from the two write paths. Committing to Git needs an HTTPS or SSH client and a credential helper, and the build copies hack/git-ask-pass.sh into /usr/local/bin. aws-cli covers private registries backed by AWS. gpg and gpg-agent cover signed commits, and tini is the entrypoint prefix so signals reach the manager process:

```dockerfile
ENTRYPOINT ["/sbin/tini", "--", "/manager"]
```

The container runs as uid 1000, a user created in the build, and the binary is statically linked through LDFLAGS carrying -extldflags "-static" with version, commit and build date injected into pkg/version at link time.

## The repository describes how to build, not how to install

The README deliberately points elsewhere for installation: the documentation at argocd-image-updater.readthedocs.io, with a stable version matching the current release and a latest version tracking the master branch. No kubectl apply snippet appears in the README.

What the repository does give you is the build interface, which is useful if you want your own image rather than the published one. The Makefile derives the image name from quay.io/argoprojlabs/argocd-image-updater by default, with the namespace overridable through IMAGE_NAMESPACE, and pushes only when IMAGE_PUSH is yes:

```makefile
IMAGE_NAMESPACE?=quay.io/argoprojlabs
IMAGE_NAME=argocd-image-updater
IMAGE_PUSH?=no
```

For local development the Makefile also wires up envtest with ENVTEST_K8S_VERSION = 1.36.0 and expects kubebuilder assets downloaded for that version. Documentation is built through a mkdocs-material image pinned at 9.7.1.

## GitOps-engine and Argo CD v3 as the coupling surface

The dependency on github.com/argoproj/argo-cd/v3 v3.5.5 is the part that will drive your upgrade schedule. Alongside it sits gitops-engine at v0.7.1-0.20250908182407-97ad5b59a627, an untagged pseudo-version, which tells you this project tracks Argo CD internals rather than a stable public interface.

Consequences follow from that. Upgrading Argo CD may pull in new APIs the updater has not been built against, and the reverse is true as well. The Kubernetes client libraries are at 0.36.1 across api, apimachinery and client-go, and the controller uses sig.k8s.io/controller-runtime 0.24.1, so the operator SDK conventions apply to anything you write in the ImageUpdater CRD.

One structural point worth understanding: this is a controller that watches ImageUpdater resources, not a CLI you run per image. GitHub webhook support is listed as done on the roadmap, meaning a registry event can trigger a check for a specific image instead of waiting for the polling interval.

## Where this is the wrong tool

It is wrong for plain YAML Applications, full stop, and that is a design decision rather than a bug.

It is also wrong when your team's process requires the image tag to be visible in the manifest itself. Overrides work, but they split the truth: a developer reading a Deployment YAML sees a stale tag and has to know that an override exists elsewhere. Teams that rely on git blame of the Deployment file to answer what is running will find that trail broken.

It is a poor fit where no registry credentials can be held, since the controller needs read access to the registry to enumerate tags. And the project's own status note should be taken at face value: it is under active development and the maintainers do not recommend it for critical production workloads yet. Development is genuinely active, with the last push on 2026-10-13 and releases v1.3.0 on 2026-08-13 and v1.3.1 on 2026-10-08, but active work is not the same as a stability guarantee.

## Licence and the CLA requirement for contributors

The code is released under the Apache 2.0 license, which is permissive for operators: you can run it internally and modify it without publishing changes, though the notice and licence text must travel with redistribution.

Contributing is a different matter. The README sets out four conditions for a pull request: unit test coverage with a stated goal of 80 percent, correct linting, comments that explain the code, and compatibility with the project's license and its CLA. A CLA means your employer may need to sign a copyright assignment, so check with legal before sending a patch from a company machine.

Also worth noting for anyone reading the repository layout: the project ships a SECURITY.md and a CODE_OF_CONDUCT.md, and the docs are built from mkdocs.yml with a readthedocs configuration, so the published documentation is generated from this tree rather than maintained separately.

## Conclusion

Adopt Argo CD Image Updater if your applications are built with Kustomize, Helm or a Config Management Plugin and you want tag bumps kept in Git as parameter overrides. Do not expect it to work on plain YAML Applications, and the README itself stops short of recommending it for critical production workloads. Before deploying, confirm on the readthedocs site which tag notation your registry supports and decide whether the Application lives in Git or is reached only through the Argo CD API.

## FAQ

### Does Argo CD Image Updater write image tag changes back to Git?

Yes, as of v0.9.0 with Argo CD v1.9.0 or later. It writes Parameter Overrides to the repository rather than modifying the application manifests, which the project describes as a compromise between keeping everything in Git and minimizing conflicts.

### Which application types does Argo CD Image Updater support?

Only Kustomize, Helm and Config Management Plugin applications. Applications built from plain YAML are not supported, and the README says further expansion depends on what functionality Argo CD provides.

### Is Argo CD Image Updater ready for production?

The project states it is under active development and that the maintainers do not recommend it for critical production workloads yet. The last push was on 2026-10-13, with v1.3.1 released on 2026-10-08.

### What registry does Argo CD Image Updater need for private images?

The controller reads tags from the registry, so it needs credentials for private registries, and the runtime image installs git, openssh-client, aws-cli, gpg and gpg-agent to support the different registry and Git authentication paths. Exact credential configuration is documented on the readthedocs site rather than in the README.

## Sources

- [argoproj-labs/argocd-image-updater on GitHub](https://github.com/argoproj-labs/argocd-image-updater)
- [License: Apache-2.0](https://github.com/argoproj-labs/argocd-image-updater/blob/master/LICENSE)
- [Project website](https://argocd-image-updater.readthedocs.io/en/stable/)
- [README](https://github.com/argoproj-labs/argocd-image-updater/blob/master/README.md)
- [Releases](https://github.com/argoproj-labs/argocd-image-updater/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/argoproj-labs-argocd-image-updater