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
- You create an Image Policy that describes how to select the “latest” version of an image
- A webhook from your registry (or a scheduled Niro poll) delivers a new tag event
- Niro evaluates the new tag against the policy
- If the tag matches and is newer than the current version, Niro opens a PR in your linked repo bumping the image tag
- 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.
| Field | Description |
|---|
| Image | The registry and image name, e.g. ghcr.io/my-org/my-app |
| Strategy | How to pick the “latest” tag (see below) |
| Linked deployment | Which Niro deployment’s manifests to update |
| Registry credential | Credentials for the registry (if private) |
Selection strategies
Semver — tracks the highest semantic version matching a constraint.
# Examples:
>=1.0.0 # any 1.x.x or higher
~1.2.0 # 1.2.x only (patch updates)
^2.0.0 # 2.x.x (minor and patch updates)
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.
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
