Guardener Container Image Suggestions

Guardener reviews pull requests that add or change container image references and recommends the Chainguard container image that replaces each upstream image. Where it can, Guardener includes the replacement as a one-click suggested change.

Note: Guardener is in beta. Available to organizations that have installed and linked the Chainguard App.

Guardener reads only the lines a pull request adds or changes, so it catches upstream images as they’re introduced but doesn’t review the images a repository already uses. To replace those images, turn on Container Image Migration, which opens a pull request for the whole repository. To list replacements for every image without changing any files, run chainctl images discover.

Prerequisites

Before you enable Image Suggestions, make sure that:

• The Chainguard App is installed and your GitHub organization is linked to your Chainguard organization, as described in Getting started. The link is needed on public repositories too, because Guardener checks each replacement against your Chainguard organization. Without a link, the pull request check reports that container image recommendations are unavailable.
• To get Image Suggestions on private repositories, your organization’s repository visibility scope is ALL. With the default PUBLIC scope, Guardener skips private repositories without leaving a comment or a check run.

Enable Image Suggestions

Add a .chainguard/images.yaml file to your repository:

enabled: true

The file turns the feature on. To opt one repository out of an organization-level default, set enabled: false in that repository’s file.

Guardener reads .chainguard/images.yaml from the pull request’s base branch, not from the pull request. A pull request that adds the file doesn’t get Image Suggestions itself. Pull requests opened after it merges do.

Choose FIPS or standard images

Images your organization already has rank ahead of images it doesn’t. Within each group, Guardener ranks the FIPS variant first when Chainguard publishes one. To rank standard images first, set prefer_fips: false:

enabled: true
prefer_fips: false

What Guardener reviews

Guardener reads the files a pull request changes and keeps only the image references on added or changed lines.

A few details apply to specific formats:

• In a Dockerfile, Guardener substitutes ARG defaults into FROM lines. It skips FROM scratch, FROM lines that name an earlier build stage, and references that depend on an ARG with no default.
• Helm values are read as written, not rendered. A reference computed inside a chart template isn’t seen. An image mapping with an empty tag uses the chart’s appVersion.
• Images used only in COPY --from or RUN --mount instructions aren’t read.

Guardener skips files under node_modules, vendor, .terraform, and testdata directories.

How Guardener responds

Guardener skips draft pull requests and reviews them once they’re marked ready for review.

For each changed reference that has a Chainguard replacement, Guardener leaves a review comment naming the replacement it selected. Guardener ranks replacements the same way as chainctl images discover and recommends the first one.

The review is non-blocking. Guardener doesn’t request changes, and its actions-recommender-images check run, which is separate from the Hardened Actions check, completes as successful or neutral, never as failed. The check run summarizes every changed reference, including the ones Guardener couldn’t recommend a replacement for.

A comment includes a one-click suggested change when all of the following are true:

• The file is a Dockerfile, YAML file, or JSON file.
• The reference is one literal value on its own line. It isn’t assembled from a Dockerfile ARG or a split Helm image mapping, and no other image shares the line.
• Your Chainguard organization already has the replacement image, with a matching tag.
• The replacement keeps a version. Guardener doesn’t suggest the latest tag for a reference with a tag that Chainguard doesn’t maintain, or for a reference pinned by digest without a tag.
• In a Dockerfile, the build stage and any stage built on it don’t run commands with RUN, a shell-form CMD or ENTRYPOINT, or an ONBUILD instruction, and don’t set CMD without ENTRYPOINT. Chainguard container images without a -dev suffix usually have no shell or package manager, and many set ENTRYPOINT to their runtime.

Otherwise, the comment names the replacement and says why it has no suggested change, so you can make the change yourself or add the image to your organization first. Adding an image isn’t always self-service: how you do it depends on your subscription, and the steps are in The container isn’t in your organization’s catalog.

A suggested change swaps one image reference for another. Guardener doesn’t restructure a Dockerfile: it doesn’t rename packages, split a build into stages, or change the user or entry point. Review and test the change as you would any other. To convert a whole Dockerfile, use Dockerfile migration.

Limits

To keep reviews fast on large pull requests, Guardener stops reading at the following limits. Anything past a limit isn’t reviewed, and the check run reports that the review stopped early.

Guardener also skips any single file larger than 1 MiB, and the check run lists it under the files it couldn’t analyze.

Configuration reference

Next steps

• Container Image Migration — Replace the images a repository already uses through one migration pull request.
• chainctl images discover — Find replacements for every image a repository already uses.
• Configuration — Set Image Suggestions once for your whole organization.
• Dockerfile migration — Convert a Dockerfile to use Chainguard container images.