[Update] - Changing Identity on Chainguard Container signatures

[Update] - We have postponed the planned change date to July 9th 2025.

Chainguard is making changes to how we sign the images in your private registry. If you verify signatures or attestations on images, you will need to make changes to that process. If you are not verifying signatures on images, there is no action required from you.
 

We currently use Sigstore to sign images in your private registry with an identity associated with Chainguard’s GitHub account. We are going to switch to signing images in your private registry with a Chainguard IAM identity in your organization. That means when verifying signatures or attestations using cosign or similar tooling, you will need to change the identity you’re verifying.
 

These new types of signatures are already available in your registry, so please update your signature verification process at your earliest convenience. Signatures associated with Chainguard’s GitHub account will be removed on July 9th, 2025.

What is changing?

• Images in your registry now contain additional signatures and attestations, signed by a Chainguard IAM identity in your organization.

• Image signatures and attestations associated with Chainguard’s GitHub account will be removed on July 9th, 2025.

Why is Chainguard making this change?

Chainguard continues to evolve how we build Chainguard Containers, with features like Custom Assembly. However, historically we’ve signed images with an identity associated with our GitHub account. Changing the identity we use for signatures makes it possible for us to continue improving our build process without being tied to a specific CI platform.

How will this affect me?

If you verify signatures or attestations of Chainguard Containers with Cosign or another tool, you will need to update the expected certificate issuer and identity. If you do not verify signatures or attestations on images, you will not be affected.

What do I need to do?

Update the issuer and identity you use when verifying signatures on images. Chainguard signs all images in your registry with one of two different identities in your organization:

• The “catalog_syncer” identity is used to sign images that have been imported directly from the Chainguard Containers catalog.

• The “apko_builder” identity is used to sign any images that have been customized for your organization, such as an image built with Custom Assembly.
   

See this example below using cosign.

PARENT=your-registry-name
IMAGE=go

# Images will be signed by either the CATALOG_SYNCER or APKO_BUILDER identity in your organization.

# Chainguard signs images from our catalog with the CATALOG_SYNCER identity.

CATALOG_SYNCER=$(chainctl iam account-associations describe $PARENT -o json | jq -r '.[].chainguard.service_bindings.CATALOG_SYNCER')

# Chainguard signs images customized for your organization with the APKO_BUILDER identity.

APKO_BUILDER=$(chainctl iam account-associations describe $PARENT -o json | jq -r '.[].chainguard.service_bindings.APKO_BUILDER')

cosign verify --certificate-oidc-issuer=https://issuer.enforce.dev \ --certificate-identity-regexp="https://issuer.enforce.dev/(${CATALOG_SYNCER}|${APKO_BUILDER})" \
  cgr.dev/${PARENT}/${IMAGE} | jq

Alternatively, you can also find the identities in the Chainguard Console. The identities are listed in the “Assumed Identities” section of the settings page for your organization. As mentioned above, images will now be signed by the “apko_builder” and “catalog_syncer” identities. Click on these identities to reveal the identity’s ID. Use this ID to verify image signatures using the same cosign command shown above.

Need help or have questions?

We're here for you. Just drop us a line at support.chainguard.dev and we’ll be happy to help.
 

-Your friends at Chainguard