Automating image updates with Argo CD Image Updater

Argo CD Image Updater moves new container tags into Argo CD applications without manual commits. This page covers how to set it up, which strategy fits your release process, and where it stops working.

On this page

How Argo CD Image Updater automates image tag changes for Argo CD applications

Argo CD Image Updater moves new container image tags into Argo CD applications so that teams do not have to commit every tag change by hand. It watches the registries behind your workloads, finds newer images that match a rule you define, and updates the application's image reference. In v1.x it is configured through ImageUpdater custom resources, which replace the annotation-based configuration used in v0.x, and it can write the resulting changes back to Git so the desired state stays in your repository. For teams that build images faster than they commit tag changes, this turns image promotion into a reviewed, traceable Git history rather than a manual edit.

The scope is narrower than a general deployment tool, and that matters for planning. Image Updater supports Kustomize, Helm and Config Management Plugin workloads only, so plain manifests and other templating approaches need a separate decision. The Argo CD Image Updater documentation describes the project as under active development, so confirm the current feature set, the configuration API and the upgrade notes against the version you intend to run before you design around a specific behavior. Ask whether your workload types are covered, which write-back method your Git host supports, and how your change control process will review commits that the updater produces on its own.

Before you adopt it, decide who is allowed to approve a new tag reaching production, and whether that approval happens in Git, in the registry, or in both. Image Updater acts on the rules you give it, so a broad tag pattern can promote a build nobody tested. Plan the registry access it needs, the Git credentials it uses for write-back, and how you will audit both. The implementation covers these choices in more detail, and the steps below assume you have already settled which workloads and environments are in scope.

What you need before enabling Image Updater

Image Updater sits on top of an Argo CD installation that already manages your workloads, so most of the preparation happens before any ImageUpdater resource is written. The cards below cover the Argo CD base, the Git credentials that carry changes back to your repositories, registry access and the network paths that tie them together.

An Argo CD installation managing supported workloads

Image Updater only updates workloads that Argo CD manages through Kustomize, Helm or a Config Management Plugin. Plain manifests and other templating approaches are outside its supported set, so inventory your Applications before you plan anything. Confirm that each target Application already syncs cleanly, because an updater cannot fix a repository or cluster problem that already blocks sync. The Argo CD installation itself depends on the Argo CD installation and deployment and high availability topics in this series.

Git write-back credentials with write access

If you want updates committed to Git rather than applied only as Argo CD parameter overrides, the updater needs credentials that can push to the application repository. Use a dedicated machine identity scoped to the repositories it must change, not a personal token. Decide which branch receives the commits, and check how your branch protection rules and required reviews treat automated commits. Store the credential as a Kubernetes Secret in the Argo CD namespace and keep it out of Git.

Registry access and pull credentials

The updater must list tags or resolve digests from each registry it watches, so every registry needs a read credential that Image Updater can use. Create a robot or service account with pull-only rights on the repositories in scope, and confirm whether your registry rate-limits anonymous or authenticated tag listing. Harbor, which your organization may run as a private registry, supports project-level role-based access control, so scope the account to the specific projects it needs.

Network paths from the cluster to registries and Git

Image Updater polls registries and pushes to Git from inside the cluster, so egress rules matter as much as credentials. Check that the controller pod can reach each registry endpoint, your Git host and any webhook sender on the ports you use. In segmented networks, route traffic through approved proxies and confirm TLS trust for private certificate authorities before the first poll. Failed polls often look like empty results, so test each path from the same namespace the updater runs in.

Confirmed Argo CD and Image Updater versions

Image Updater configuration changed across releases, and the v1.x ImageUpdater custom resources replaced the v0.x annotation model. Before installing, read the Image Updater documentation for the release you plan to run, then confirm it supports your Argo CD version. Argo CD itself has moved through major upgrades with breaking changes, so check your installed version against the upgrade notes and confirm which minor lines your team can patch. Ask your vendor or your own test cluster to validate the combination you intend to deploy.

Image update policy and approval rules

Decide before enabling anything which tag changes may reach each environment without a person approving them. Semver constraints, newest-build and digest strategies behave differently, and a loose constraint can promote a build you did not intend to ship. Write the rules down per environment and map them to who reviews the resulting Git commits. This decision shapes the rest of the setup more than any single setting.

Configuring an ImageUpdater resource step by step

This sequence takes Image Updater from installation to a verified update path, with a check at each step so every stage is confirmed before the next one depends on it. The final step proves the full chain works, from a new tag in the registry to a synced Argo CD Application.

  1. Install Image Updater in the Argo CD namespace

    Install Argo CD Image Updater into the same namespace as your Argo CD installation so it can read Application resources and the ImageUpdater custom resources it uses. The team that already runs Argo CD usually owns this step, and the installation method should follow the Image Updater documentation for the version you choose. Confirm that the controller pod is running and that the ImageUpdater custom resource definition exists in the cluster, because v1.x configuration depends on it. The step is done when the logs show Image Updater starting without errors.

  2. Configure access to the image registry

    Give Image Updater read access to the registry that holds your application images, using credentials stored as Kubernetes Secrets in the Argo CD namespace. Private registries such as Harbor need an account with pull permission only, scoped to the projects that hold the images you intend to update. Confirm the authentication method against the registry configuration section of the Image Updater documentation for your version. The step is done when the logs show Image Updater listing tags for the image without authentication errors.

  3. Create the ImageUpdater resource for the application

    Create an ImageUpdater resource that names the image to watch and points at the Argo CD Application it should update. The resource identifies the image, its registry path and the Application target, and Image Updater supports only Kustomize, Helm and Config Management Plugin workloads, so confirm the Application uses one of those tools before you start. Keep this resource in Git with the rest of the platform configuration. The step is done when the cluster accepts the resource and the logs show Image Updater finding the current tag for the image.

  4. Select the update strategy for the image

    Choose one strategy for each image: semver to follow a version range, newest-build to follow the most recent build, alphabetical to order tags by name, or digest to track a mutable tag whose content can change under the same name. Semver suits images that publish version numbers, newest-build suits pipelines that tag every build, and digest suits mutable tags. Test the choice against the tags that already exist in your registry, because a pattern that matches nothing produces no update. The step is done when the logs show the expected candidate tag selected from that test list.

  5. Set the write-back method to Git or parameters

    Pick a write-back method. Git write-back commits the new tag to the repository that holds the manifests, which keeps every change in Git history and suits change control that expects a commit. Argo CD parameters update the Application directly, which leaves no commit, so teams that choose this method need another audit source for tag changes. Agree the choice with your security and compliance owners before enabling it, and confirm the repository credentials that Git write-back requires. The step is done when a test change produces either a commit on the target branch or an updated parameter on the Application.

  6. Verify the update with a test image push

    Push a non-production test image with a tag that matches the strategy you chose, then follow the full path: Image Updater detects the tag, writes the change back, and Argo CD syncs the Application. Add registry webhooks only after this path works, since webhook-triggered updates are supported for Docker Hub, GitHub Container Registry, Quay and Harbor and would add a second trigger to troubleshoot. Confirm the Git commit or parameter change, the sync result and the image running in the pod. The step is done when the pod runs the test tag and the commit history or Application shows who changed it.

Choosing semver, newest-build, alphabetical or digest for your release process

Use the semver strategy when your team publishes stable releases under version numbers and wants Image Updater to follow those releases into an environment. The strategy compares tags as versions, so the tagging scheme carries the release decision. This suits production environments where a release is a deliberate act by the owning team, and it places the control in how versions are assigned and published. Review the Argo CD Image Updater documentation for the constraint syntax your version supports.

  • Accidental promotion: a pre-release or unusual tag that parses as a higher version can be selected if your constraint allows it. Confirm how pre-release identifiers are handled before you rely on the default behavior.
  • Tag immutability: each version tag should point to one image and never be moved or deleted. Retagging an existing version breaks the guarantee that a version means one artifact.
  • Consistent format: use one format across a repository, such as three-part numeric versions, so that ordering is predictable. Mixing formats like v1.4 and 1.4.0 in the same image makes selection harder to reason about.
  • Scoped constraints: limit the allowed version range per environment so that a major version change requires a separate, reviewed decision.

Before enabling semver on a production application, confirm how your release process creates, moves and deletes tags, and whether any tag can be overwritten by a pipeline.

When registry webhooks replace polling for Docker Hub, GHCR, Quay and Harbor

Use registry webhooks only when the registry is one of the four that Image Updater supports for webhook-triggered updates: Docker Hub, GitHub Container Registry, Quay and Harbor. For these, a push event can start an update within moments instead of waiting for the next polling cycle. Any other registry stays on polling, so the update delay is set by how often Image Updater checks the registry, and you should plan the rollout window around that interval rather than around a push time. Confirm the current webhook setup steps and payload handling in the Argo CD Image Updater documentation before you build anything, because the project describes itself as under active development.

On the registry side, you must create a webhook that points at the Image Updater endpoint, supply the shared secret the webhook sends, and limit the webhook to the repositories whose tags should trigger updates. Each registry names these settings differently, so record the exact fields you configured. The endpoint is the part to review with your security team: it accepts unauthenticated inbound requests from the registry, so it must be reachable from the registry's source addresses and nowhere else. Put it behind an ingress with TLS, restrict who can reach it at the network layer where possible, and check that a forged request cannot trigger a deployment on its own.

If Harbor is your registry, treat its webhook behavior as a version-specific check. Harbor v2.15.3 blocks webhooks to internal network addresses by default, which breaks a setup where Harbor calls an Image Updater service inside the cluster network. Read the Harbor release notes for the version you run, then confirm whether your webhook target is affected and whether you need to change that default or move the endpoint. Review the Harbor GitHub releases page as the next step, and retest the webhook path after every Harbor upgrade, since a silent break leaves you on polling without an alert.

Mapping registry tags, Argo CD parameters and Git fields

This table maps each place a new image version is read from, decided, recorded and observed, from the registry tag through the Application target to the Git commit and the sync result. Read it left to right when you build or debug a pipeline, and confirm the exact field names against the Image Updater version you run, since the documentation describes the ImageUpdater resource model as under active development. The main takeaway is that a tag change only reaches the cluster after Image Updater writes it to Git or Argo CD sees it in the manifest source, so each hop needs its own check.

Source of truthWhat it holdsWhat to verify
Registry repository and tagThe image name and the tags Image Updater lists from the registry, such as Docker Hub, GHCR, Quay or HarborConfirm the registry credentials can list tags and that the repository path matches the image in the workload
ImageUpdater strategy fieldThe update strategy, one of semver, newest-build, alphabetical or digest, which decides which tag is chosenConfirm the strategy name against your version, since the documentation lists these four options
Argo CD Application targetThe Application whose Kustomize, Helm or Config Management Plugin source contains the image reference Image Updater changesConfirm the workload type is one the documentation supports, because other source types are not covered
Git file and key updated on write-backThe manifest file and key that Image Updater rewrites when it commits to Git, such as a Kustomize image entry or Helm values keyConfirm the write-back target and the exact key in a test repository before enabling it on a production branch
Commit author and messageThe identity and text recorded on the commit Image Updater creates, which become the audit trail for the changeConfirm the commit identity your Git host accepts and that branch protection allows the bot account to push
Sync result observed in Argo CDWhether the Application reports the new image in its live resources and reaches a Synced and Healthy stateConfirm the Application shows the new tag in its resource tree and that the rollout completes without drift

Securing registry credentials, Git write-back and repo-server exposure

Image Updater works with three trust relationships: read access to registries, write access to Git, and an inbound webhook. Each one needs its own identity, scope and check. The cards below cover the controls to set before automated tag changes reach production.

Dedicated Git identity for write-back

Give Image Updater its own Git account or GitHub App, with write access only to the repository that holds the images it updates. Do not reuse a personal token or a CI account that can push elsewhere. Check which branch the identity can push to, and confirm the exact write-back method your Image Updater version supports before you configure it.

Read-only registry credentials

Scope registry credentials to pull access on only the repositories that Image Updater needs to read. Use separate robot or service accounts per registry, and rotate them on a schedule your security team sets. Confirm how each registry you use issues read-only tokens, since the options differ by provider.

Shared secret on the webhook endpoint

Webhook-triggered updates should accept requests only when they carry a shared secret that the registry signs or sends. Store the secret in a Kubernetes Secret, not in a ConfigMap or Git. Check that the webhook path is reachable only from the registry's sources, and confirm the verification method for each registry you connect.

Branch protection for automated commits

Write-back commits bypass the pull request review that people normally go through, so protect the target branch with required reviews or status checks. Decide whether Image Updater commits directly to the deployment branch or to a separate branch that a reviewer merges. Test the protection rules with a dry run before enabling automatic updates.

Repo-server running Helm and Kustomize

The repo-server runs Helm and Kustomize against repository content, so anyone who can change the chart or overlay can influence what runs in the cluster. Limit which repositories Argo CD trusts, and restrict out-of-tree file references in projects. Review how image parameters are rendered before trusting a tag change that passed through the template.

Credential redaction in logs and API

Argo CD redacts cluster, Git and OAuth2 credentials from API responses and logs, and it authenticates API requests only with JSON Web Tokens. Image Updater logs still need checking, because registry tokens and Git credentials can appear in debug output. Confirm the log level in production, forward logs to a restricted store, and test redaction with a sample credential.

Why tags stop updating and how to diagnose them

This table pairs common symptoms of stalled image updates with their likely causes and the first fix to try. Read each row as a checklist: start with the symptom you see, confirm the cause in the Image Updater logs and the Git history, then apply the fix. Most failures sit in the strategy and annotation setup, the write-back path or the Helm and Kustomize target, not in the registry itself.

SymptomLikely causeDiagnosis and fix
No commit after a new tag is pushedThe strategy pattern or tag constraint does not match the new tag, so Image Updater ignores itCheck the ImageUpdater allow-tags or semver constraint against the exact tag name. Confirm the strategy suits how your team names builds, then correct the pattern and wait for the next poll.
No commit after a new tag is pushedNo registry webhook is configured, so updates depend on the polling interval onlyConfirm the registry is one of the webhook-supported types. If it is, configure the webhook to call Image Updater. If it is not, accept polling and confirm the interval is acceptable.
No commit after a new tag is pushedImage Updater cannot authenticate to the registry, so it sees no tagsReview the Image Updater logs for registry access failures. Create or correct the pull secret or registry credentials it uses, and test the same credentials with a manual pull.
Write-back commit is rejectedThe Git branch is protected and the Image Updater identity cannot push to itGrant the write-back identity push rights on the target branch, or write to a dedicated branch and merge through your review process. Confirm the identity has the same access on every repository it updates.
Write-back commit is rejectedWrite-back credentials are missing or expired for the repositoryCheck the repository credentials Image Updater uses for write-back. Rotate them if they have expired, and store them the same way as other repository secrets.
Update lands on the wrong Helm values pathThe image parameter target in the annotation points to a key that is not used by the chartRender the chart locally with the same values file and find the key that sets the image. Correct the target path so the tag, not a neighboring field, changes.
Update lands on the wrong Helm values pathThe chart uses separate repository and tag keys, and only one is being writtenConfirm how the chart splits the image reference. Configure the updater to write both fields or the field the chart actually reads.
Kustomize override is not appliedThe image name in the ImageUpdater does not match the image name in the kustomization fileCompare the image name in the kustomization images list with the name Image Updater tracks. Align the names exactly, including registry prefixes.
Kustomize override is not appliedThe write-back target file is not the overlay Argo CD rendersConfirm the application source path and the overlay that holds the image entry. Point the updater at that overlay, then check the rendered manifest in Argo CD.
Argo CD does not sync after write-backArgo CD is not watching the branch that received the commitConfirm the application target revision matches the branch Image Updater wrote to. Correct either side so both use the same branch.
Argo CD does not sync after write-backThe application uses manual sync or an automated sync policy that is pausedCheck the sync policy on the application. If automated sync is intended, confirm it is enabled and that no sync window blocks the change.
Argo CD does not sync after write-backArgo CD has not refreshed the repository yet because webhook delivery or polling is delayedTrigger a manual refresh on the application to confirm the commit is visible. Then review repository webhook delivery or the refresh interval.
Tag rolls back unexpectedlyA newer commit from another author or pipeline overwrote the image valueReview the Git history for the file. Identify the other writer and agree on one owner for the image field, or separate environment overlays.
Tag rolls back unexpectedlyThe semver constraint or newest-build pattern selected an older tag after a rename or retagReview the tag list in the registry and the selected tag in the logs. Narrow the constraint so it only matches release tags, and avoid reusing tag names for different builds.
Tag rolls back unexpectedlyA manual revert or Argo CD rollback restored a previous Git state that Image Updater then re-appliedConfirm whether the revert was intended. If it was, pin the tag in the overlay or pause the updater for that application until the release is ready.

Questions teams ask before automating image updates

What drives the effort and cost of automating image updates with Argo CD Image Updater?

The main drivers are how many Argo CD applications need automated updates, how consistently your teams tag images, how many registries you pull from, and whether your manifests are Helm charts, Kustomize overlays or a mix. Each application needs an ImageUpdater resource with a strategy, an allowed tag pattern and a write-back method, so the count of applications sets most of the configuration work. Tagging discipline matters as much: if tags are inconsistent, semver or newest-build rules will pick the wrong image. Ask any partner to price the work against a written list of applications, registries, chart types and the review workflow you need, since those inputs determine the quote.

How long does it take to get a working pilot of Image Updater?

The duration depends on the scope you agree in writing, not on a fixed period. A pilot usually covers a small set of applications in one non-production cluster, with one registry, one strategy and one write-back path, so it is faster when the pilot is narrow and the images already follow a clear tagging convention. Delays tend to come from access approvals, unclear promotion rules and registry configuration rather than from the Argo CD side. Ask for the planned pilot milestones, what the pilot must prove before it is extended, and which of your team members must be available for reviews.

What must our team provide before the work starts?

You need to provide four things: read and write access to the Git repositories that hold the manifests Image Updater will change, read access to the container registries it will poll, a Kubernetes context or access path to the clusters running Argo CD, and a decision on promotion policy. The promotion decision is the one most often missing. You must decide which tags may reach which environments, who approves a change, and whether updates go straight to production or pass through a gate. Image Updater can write back to Git, but it cannot make that governance decision for you. Confirm credential handling for both Git and registries before the build begins.

Can an in-house platform team build this without outside help?

Yes, a platform team with working Kubernetes, Argo CD and Git administration skills can build it, and many do. The skills that often take the longest to build are registry authentication, safe Git write-back with branch protection, and testing semver and digest rules against real tag histories. Image Updater is also described as under active development, so your team will need to track release notes and upgrade paths. Decide whether the team has capacity for the initial build and for ongoing maintenance, and whether an external partner should review the design, handle the build, or support it on a retainer.

Is Argo CD Image Updater suitable for production promotion?

It can be, but only when the promotion rules are explicit. Image Updater is a good fit for moving new builds into development or staging automatically, and for production when your policy allows tags to flow without a manual step. Where production needs approval, the safer pattern is to have updates land as reviewed commits or pull requests rather than direct write-back. Before using it in production, confirm the current release status against the project documentation, test rollback by reverting a Git commit, and make sure a registry outage or a bad tag cannot silently reach a production namespace. Your change management team should sign off on the flow.

How does Image Updater work with Harbor when Harbor is our registry?

Image Updater reads tags from whatever registry hosts your images, and Harbor is one of the registries it can poll. It can also receive webhook-triggered updates from Harbor, so new pushes can prompt an update rather than waiting for the polling interval. Harbor adds the registry-side controls: projects with role-based access, vulnerability scanning through Trivy, replication to other registries, and proxy cache projects. Those controls should be designed in Harbor, while Image Updater handles the tag selection and Git change. Check that Harbor's webhook settings allow the traffic path you choose, because recent Harbor releases block webhooks to internal network addresses by default.

What should we check on Helm and Kustomize workloads before automating?

Image Updater supports Kustomize, Helm and Config Management Plugin workloads, but the write-back and parameter handling differ by tool, so test each type separately. Confirm which file or parameter holds the image reference, whether the value is set in a values file, an overlay or a chart default, and whether a second source overrides it. Charts that build images indirectly or that template the tag in several places need extra care. Plan a test on a copy of one application from each tool before you commit to a pattern across the estate, and document any manifest that Image Updater cannot update safely.

How DeployOpen scopes and delivers Image Updater automation

DeployOpen plans, implements, integrates, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure, including Argo CD deployments. For image update automation, we agree the strategy per application, the registry path, the write-back method and the approval gates in writing before any configuration changes are made.

How we scope

  • Inventory which Argo CD applications use Kustomize, Helm or Config Management Plugin sources, since Image Updater supports only those workloads.
  • Record the update strategy chosen per image, such as semver, newest-build, alphabetical or digest, and who approves each tag range.
  • Agree in writing whether updates write back to Git or stay in Argo CD parameters, and which repositories and branches are in scope.

How we build

  • Define ImageUpdater resources in version 1.x, with registry credentials stored as Kubernetes Secrets and scoped to the namespaces that need them.
  • Test each strategy against a staging registry and Git repository, confirming the commits, tag selection and rollback path before production use.
  • Configure registry webhooks only where the registry is supported and the internal network path to the Image Updater endpoint is approved.

How we hand over

  • Document every ImageUpdater resource, strategy, write-back identity and alias with the owner and the approval rule for each application.
  • Walk your platform and security engineers through the runbook, including how to pause updates and revert a bad automated commit.
  • Deliver the verification steps, sync checks and access review evidence in a form your change management and audit teams can use.

How we support

  • Support is available as a retainer for version upgrades, since Image Updater is described as under active development and its configuration may change.
  • Retainer work can cover reviewing new strategies, registry changes and Argo CD upgrades that affect update automation, scoped in writing.
  • Confirm with DeployOpen during scoping which upgrade and review tasks are covered by fixed-scope delivery and which fall under a retainer.

Talk to our team.

Tell us what you're working on, whether it's a deployment, an audit, a security test or a cyber range. You'll speak with an engineer who can help you scope it.

  • 30-minute call: free, with no obligation.
  • NDA on request: we can sign before you share details.
  • Clear next steps: a scope and plan after the call.