Skip to main content

​
Overview

Image Automation watches your container registries for new image tags and automatically opens a pull request in your linked GitHub repo to bump the image reference in your manifests. When the PR is merged, Niro applies the updated manifests to your cluster — completing a fully automated image promotion pipeline.

​
How it works

  1. You create an Image Policy that describes how to select the “latest” version of an image
  2. A webhook from your registry (or a scheduled Niro poll) delivers a new tag event
  3. Niro evaluates the new tag against the policy
  4. If the tag matches and is newer than the current version, Niro opens a PR in your linked repo bumping the image tag
  5. You review and merge the PR — or enable auto-merge for fully automated promotion

​
Image policies

An image policy defines the selection strategy for a given image. Navigate to Image Automation in the sidebar and click New policy.

​
Selection strategies

Semver — tracks the highest semantic version matching a constraint.
Newest build — always use the most recently pushed tag (by registry push timestamp). Good for CI builds that don’t follow semver (e.g. commit SHA tags). Digest — track a mutable tag (like latest or stable) by pinning its digest. When the digest behind the tag changes, Niro opens a PR to update the pinned digest in your manifests.

​
Setting up registry webhooks

For real-time detection (rather than polling), configure a registry webhook to point at Niro’s webhook endpoint shown on the Image Automation page. GHCR: GitHub sends package events automatically when you connect via the GitHub App. No extra setup needed. Docker Hub: In your Docker Hub repository settings, add a webhook pointing to the Niro endpoint. Other registries: Consult your registry’s documentation for webhook configuration. Without a webhook, Niro polls registered images on a scheduled interval (every 5 minutes on Pro+).

​
Auto-merge

By default, Niro opens a PR and waits for you to review and merge it. To enable fully automated promotion without human review, toggle Auto-merge on the policy.
Auto-merge is irreversible in the sense that the cluster will update without a human in the loop. Only enable it for non-production clusters or images from a well-tested CI pipeline.

​
Pinning a specific version

To pause automatic updates for a deployment, disable the image policy. Niro will stop opening PRs for that image until you re-enable it. To pin to a specific digest, use the Digest strategy with your current image digest. Niro will open a PR only when the digest behind the tracked tag changes — meaning only when you intentionally change the digest.

​
Policy conflicts with mutable tags

If your image policy tracks a mutable tag like latest, the latest-image-tag policy rule will fire as a finding on the deployment. This is by design: mutable tags are a reliability risk. Use the Digest strategy to track mutable tags by their immutable digest — you get the convenience of mutable tags with the reproducibility of digest pinning.
  • Set Up GitOps — required for image automation (manifests live in a linked repo)
  • Private Registries — registry credentials for private images
  • Policies — latest-image-tag rule and other standards checks
  • Plans — image automation is available on Pro+ plans
Last modified on June 10, 2026