Learn GitOps with ArgoCD - Image Updater - Automated Image Updates

#Introduction

In episode 15 we built a Git- and tag-based promotion workflow. But there's one link still manual: who changes the image version in the manifests? CI/CD can build new images, but it still takes human hands to type v1.2.4 in a kustomization or Helm values, open a PR, and wait for review. In this episode we discuss ArgoCD Image Updater — a controller that checks registries, detects new images, and updates manifests automatically, while still respecting the GitOps flow.

Why does this matter? GitOps doesn't mean "everything must be manual". Image Updater is the bridge that connects CI push to registry with ArgoCD pull from Git — a complete automatic cycle from code commit to deploy. More importantly, it can be set differently per environment: fully automatic in dev, controlled in staging, and waiting for approval in production.

#Installation & Setup

Image Updater runs as a separate Deployment in the argocd namespace. The easiest installation is with Helm:

helm repo add argo https://argoproj.github.io/argo-helm
helm install argocd-image-updater -n argocd \
  argocd/argocd-image-updater
kubectl rollout status deploy/argocd-image-updater -n argocd

Registry credential configuration lives in the argocd-image-updater-secret Secret, while global settings (e.g. default registries) go in the argocd-image-updater-config ConfigMap.

#How It Works

The controller scans all Applications every interval (default 2 minutes), looking for certain annotations. If found, it:

1. Checks the registry for the latest image matching the rules.
2. Determines the tag selection strategy (semver, latest, digest, name).
3. Updates the image version in the manifests — via write-back to Git (commit) or write-back to ArgoCD (changing Application parameters).
4. ArgoCD detects the change and syncs the application as usual.

Because the process starts from reading annotations on the Application, no application code changes are needed — Image Updater works purely at the manifest layer.

#Configuration through Annotations

All per-application behavior is set through annotations on the Application:

application.yaml with annotations

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: billing-api
  namespace: argocd
  annotations:
    argocd-image-updater.argoproj.io/image-list: |
      api=ghcr.io/devnull/billing-api
      web=ghcr.io/devnull/web
    argocd-image-updater.argoproj.io/api.update-strategy: semver
    argocd-image-updater.argoproj.io/api.allow-tags: regexp:^v?[0-9]+\.[0-9]+\.[0-9]+$
    argocd-image-updater.argoproj.io/web.update-strategy: digest
spec:
  project: default
  source:
    repoURL: https://github.com/devnull/gitops-repo.git
    path: apps/billing/overlays/prod
    targetRevision: main
  destination:
    server: https://kubernetes.default.svc
    namespace: billing-prod

• image-list lists the monitored images, with an alias per image (api, web).
• Each alias has its own annotation, e.g. api.update-strategy and api.allow-tags.

#Update Strategies

Four strategies are available:

The semver strategy is the safest choice for production: only tags satisfying allow-tags are considered, so odd tags like canary-abc never get picked.

#Write-Back Methods

How Image Updater writes its results back:

#Write-back to Git

The most GitOps method: the controller commits to the manifest repository with a message like chore: updated billing-api image v1.2.3. That change is reviewed, audited, and rollback-able via revert — exactly the flow from episode 15. It needs commit credentials in the argocd-image-updater-secret Secret.

#Write-back to ArgoCD

An alternative method: Image Updater changes the image parameter directly on the Application (equivalent to argocd app set --helm-set image.tag=v1.2.3). Simpler because it doesn't need Git access, but the change is not recorded in Git — a trade-off that reduces the GitOps audit benefit. Use it only when write-back to Git isn't possible.

Enabling git write-back

  annotations:
    argocd-image-updater.argoproj.io/image-list: |
      api=ghcr.io/devnull/billing-api
    argocd-image-updater.argoproj.io/api.update-strategy: semver
    argocd-image-updater.argoproj.io/api.write-back-method: git
    argocd-image-updater.argoproj.io/api.git-branch: main

#Automation Patterns per Environment

Image Updater's power is in the different policies per environment:

• Dev — fully automatic. update-strategy: latest + write-back-method: argocd → every push to the registry immediately syncs dev. No review, as befits a development environment.
• Staging — controlled. semver with strict allow-tags, write-back to Git on the staging branch; changes show up as commits that can be lightly reviewed.
• Production — manual approval. Production does not get auto-update annotations; promotion happens through a PR (episode 15) that explicitly bumps the tag. Image Updater can be used here only as an information provider (e.g. showing the latest tag), not as an automatic changer.

#Integration with CI/CD

The ideal end-to-end flow:

1. CI builds the image and pushes it to the registry with a semver tag (episode 18 will detail the pipeline).
2. Image Updater detects the new tag on the next interval.
3. Image Updater updates the manifests — a commit to Git (for git write-back) or updating the Application parameters.
4. ArgoCD detects the manifest change and syncs the application.

This way the chain "code commit → new image → new manifest → deploy" is hands-free in lower environments, and still reviewed in higher environments.

#Best Practices

• Semantic versioning — mandate semver tags; other strategies (latest) easily produce "unexpected deploys".
• Digest pinning — for production, consider update-strategy: digest so the deployed image is always reproducible and immune to overwritten tags.
• Branch protection — protect the main/prod branches with required reviews; automatic commits from Image Updater must still pass CI checks.
• Minimal credentials — give Image Updater credentials scoped to commit on a single repository only, not a Git admin account.
• Notifications — set up alerting (episode 17) to know when Image Updater changes something and when a sync fails.

#Common Pitfalls

1. The latest tag in production. Hard to roll back and not reproducible. Use semver or digest.
2. Inconsistent alias annotations. The alias name in image-list must match the api.update-strategy annotation prefix exactly.
3. Forgetting registry/commit credentials. Image Updater stays silent with no clear logs if the Secret doesn't contain the right credentials.
4. Disabling auto-sync but expecting a deploy. Image Updater changes manifests; if the Application uses manual sync, the change won't be deployed until a sync happens.
5. Full automation on every environment. Losing the approval gate in production is a risk not worth taking.

#Closing

This episode closed the automation loop: installing Image Updater with Helm, how the scanning controller works, the semver/latest/digest/name update strategies, the two write-back methods (Git vs ArgoCD), per-environment automation patterns from automatic dev to production with approval, CI integration, and best practices for semver, digest pinning, and branch protection.

The points you should take with you:

• Image Updater connects CI push to registry with ArgoCD pull from Git.
• update-strategy: semver is the safest choice for releases.
• Write-back to Git keeps the audit trail; write-back to ArgoCD is simpler but leaves Git out.
• Full automation is only for lower environments; production needs approval.
• The image-list annotation and aliases are the key to all configuration.

Good automation must be visible — the team needs to know when a deploy succeeds, fails, or waits. In the next episode 17 we discuss Notifications & Alerts: argocd-notifications, triggers and templates, subscriptions to Slack/Teams/email/webhook, and patterns for deploy notifications, failure alerts, and audit trails. See you in episode 17!