Skip to content
BoringStack
Star

ArgoCD image updater

2 min read

The k3s target closes the deploy loop with argocd-image-updater: when CI pushes a new GHCR image, the updater rewrites the tag in overlays/prod/kustomization.yaml and ArgoCD syncs it. All config lives in annotations on infra/k3s/argocd/boringstack-prod.yaml.

The annotations

Section titled “The annotations”
argocd-image-updater.argoproj.io/image-list: api=ghcr.io/<owner>/<project>-api, ui=ghcr.io/<owner>/<project>-ui
argocd-image-updater.argoproj.io/api.update-strategy: newest-build
argocd-image-updater.argoproj.io/api.allow-tags: regexp:^sha-[0-9a-f]{7,40}$
argocd-image-updater.argoproj.io/write-back-method: git:secret:argocd/image-updater-git-creds
argocd-image-updater.argoproj.io/write-back-target: kustomization
argocd-image-updater.argoproj.io/git-branch: main

image-list pairs an alias with each image the updater watches.

update-strategy: newest-build plus the ^sha- regex tracks the newest sha-<short> build. BoringStack’s release workflows tag every push to main as latest + sha-<short> (and a semver tag on a v* release), so this matches the sha- form and ignores latest. To deploy only tagged releases instead, use update-strategy: semver with allow-tags: regexp:^v?\d+\.\d+\.\d+$.

write-back-method: git commits the tag bump back to your repo (the GitOps source of truth) using the argocd/image-updater-git-creds secret. write-back-target: kustomization edits the images: block rather than the Application spec.

Bootstrap

Section titled “Bootstrap”
  1. Install argocd-image-updater in the argocd namespace.
  2. Create the git write-back credential it references:
    Terminal window
    kubectl -n argocd create secret generic image-updater-git-creds \
      --from-literal=username=<git-user> \
      --from-literal=password=<git-PAT-or-deploy-token>
    (Or an sshPrivateKey key for SSH write-back.)
  3. Give it pull access to GHCR (a registry pull secret or --registries-conf) so it can read tags from your private packages.

Troubleshooting

Section titled “Troubleshooting”

No updates happen: check the image-updater pod logs and confirm the allow-tags regex matches the tags CI actually publishes.

Updates detected but not committed: the git creds secret is missing or lacks push rights to main.

Tag bumped but the app didn’t change: confirm the Application’s images: block names match image-list exactly (registry plus repo path).

Section titled “Related”