> ## Documentation Index
> Fetch the complete documentation index at: https://docs.niro.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Image Automation

> Automatically open PRs when new container image versions are published.

## 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**.

| 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)
```

**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.

<Warning>
  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.
</Warning>

## 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](/features/policies) 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.

## Related

* [Set Up GitOps](/guides/gitops) — required for image automation (manifests live in a linked repo)
* [Private Registries](/guides/private-registries) — registry credentials for private images
* [Policies](/features/policies) — `latest-image-tag` rule and other standards checks
* [Plans](/reference/plans) — image automation is available on Pro+ plans