Image Updater Bots

Summary

• Definition: An image updater bot watches your registry for new image tags, applies a policy to pick the right one, and writes that image back into git so the GitOps controller deploys it.
• Insight: The bot closes the loop from "CI pushed an image" to "git reflects the new image" without any human editing a manifest or any CI job holding cluster credentials.
• Key Concepts: image policy, semver constraint, write-back to git, digest pinning, image reflector.
• When to Use: When you want new builds to flow into an environment automatically under a tag policy, especially non-production, while keeping git as the source of truth.
• Limitations: Auto-updating production without a promotion gate is risky; policies must be tight, and write-back needs a scoped git credential.

Recipe

1. Tag images from CI with a policy-friendly scheme (semver or timestamp).
2. Install Flux's image automation controllers, or Argo CD Image Updater.
3. Declare a policy that selects which tags are eligible (for example >=1.2.0 <2.0.0).
4. Point the automation at the manifest field to rewrite.
5. Let the bot commit the update to git so the GitOps controller syncs it.

Working Example

This uses Flux image automation. It needs three objects: an ImageRepository to scan the registry, an ImagePolicy to select a tag, and an ImageUpdateAutomation to write back to git.

apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImageRepository
metadata:
  name: api
  namespace: flux-system
spec:
  image: registry.example.com/api
  interval: 5m
---
apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImagePolicy
metadata:
  name: api
  namespace: flux-system
spec:
  imageRepositoryRef:
    name: api
  policy:
    semver:
      range: ">=1.2.0 <2.0.0"

The automation object commits the selected image back to the manifest repository.

apiVersion: image.toolkit.fluxcd.io/v1beta1
kind: ImageUpdateAutomation
metadata:
  name: api
  namespace: flux-system
spec:
  interval: 5m
  sourceRef:
    kind: GitRepository
    name: flux-system
  git:
    checkout:
      ref: { branch: main }
    commit:
      author:
        name: fluxcdbot
        email: fluxcdbot@example.com
      messageTemplate: "auto: update {{range .Updated.Images}}{{println .}}{{end}}"
    push:
      branch: main
  update:
    path: ./overlays/staging
    strategy: Setters

Flux rewrites fields you mark with a setter comment. The comment names the policy whose selected image and digest should be substituted.

spec:
  template:
    spec:
      containers:
        - name: api
          # {"$imagepolicy": "flux-system:api"}
          image: registry.example.com/api:1.2.0

When a new 1.x tag is pushed, Flux resolves it to a digest, rewrites the image: line, commits, and the Kustomize controller deploys it.

Deep Dive

How the scan and selection works

The image reflector controller lists tags from the registry on the interval. It caches the tag list and each tag's digest.

The ImagePolicy filters that list. Semver policies parse tags as versions and pick the highest one inside the range.

For non-semver schemes, a numerical or alphabetical policy with a tag filterTags regex handles timestamp or build-number tags.

policy:
  numerical:
    order: asc
filterTags:
  pattern: "^main-[a-f0-9]+-(?P<ts>[0-9]+)$"
  extract: "$ts"

Argo CD Image Updater as an alternative

Argo CD Image Updater is configured with annotations on the Application. It supports write-back to git so the change still flows through Argo CD's normal sync.

metadata:
  annotations:
    argocd-image-updater.argoproj.io/image-list: api=registry.example.com/api
    argocd-image-updater.argoproj.io/api.update-strategy: semver
    argocd-image-updater.argoproj.io/api.allow-tags: "regexp:^1\\."
    argocd-image-updater.argoproj.io/write-back-method: git

The write-back-method: git setting is important. The alternative writes to a live parameter override, which creates drift between git and the cluster.

Pinning to digests

Both tools can pin the resolved digest, not just the tag. Deploying by digest keeps the rollout deterministic even if the tag is later re-pushed.

Flux writes the digest when the policy and setter are configured to do so; Argo CD Image Updater has a pin-digest strategy for the same purpose.

Scoping the write-back credential

The bot needs a git credential that can push to the manifest branch. Scope it to that one repository and, ideally, to a protected automation branch.

Registry read credentials should be scoped to pull metadata only. Neither credential should have cluster API access.

Gotchas

Auto-updating production. Point automation at non-production environments and promote to production through a reviewed PR. Unattended prod bumps remove your last human gate.

Loose tag filters. A policy of "any tag" will happily deploy a broken feature-branch build. Constrain to semver ranges or a strict branch pattern.

Tag races. If CI re-pushes a mutable tag, a tag-only update can flip the running image. Pin digests so the deployed artifact never changes underneath you.

Commit loops. Misconfigured write-back can fight another automation and spam commits. Keep exactly one writer per path and use a dedicated bot identity.

Signature verification. The bot does not verify signatures. Keep admission-time verification (Kyverno or the Sigstore policy controller) in place so an updated image is still checked.

Alternatives

Manual promotion in CI. CI writes the new digest into git directly with kustomize edit set image. Simplest and fully explicit, but every bump is a pipeline job.

Renovate. Renovate raises pull requests for image and chart bumps, which suits teams that want review on every change rather than auto-merge to staging.

No updater (pure push). CI commits the manifest change itself. This is the recommended baseline; add an updater only when you want registry-driven automation.

Pick a bot when new builds are frequent and you want them to reach staging without human toil. Keep production behind an explicit promotion regardless of the tool.

FAQs

Does the bot deploy to the cluster? No. It commits to git; the GitOps controller (Flux or Argo CD) performs the actual sync.

Semver or timestamp tags? Semver gives the cleanest policies. Timestamp or build-number tags work with numerical policies and a filterTags regex.

Can it write back digests instead of tags? Yes. Both Flux and Argo CD Image Updater can pin the resolved digest for deterministic rollouts.

Should production auto-update? Generally no. Automate staging, then promote to production through a reviewed pull request.

What credentials does it need? Registry read for metadata and a git push credential scoped to the manifest repo. It never needs cluster API access.

How do I stop a bad auto-update? Revert the bot's commit in git; the controller reconciles the previous image back in.

Related

• From Commit to Running Pod
• Deploy Pipeline Basics
• Progressive Delivery
• CI/CD Best Practices

Stack versions: This page was written for Kubernetes 1.36.2, Docker Engine 29.6.1 (BuildKit default), containerd (CRI runtime on nodes), Helm 3, Compose v2, Argo CD (latest - verify at build), and Gateway API (GA - verify controller support at build).