Verify images and signatures¶

Configure StageX image signature verification with OCI lookaside signatures.

What signature verification proves¶

Signature verification proves that maintainers signed the image digest you are pulling. It does not prove that you independently rebuilt the artifact. For that, follow Reproduce StageX.

StageX publishes signatures for released images in the StageX signatures repository. The repository includes the published signature files and a stagex-keyring.pgp keyring for maintainer public keys, and stores signatures as OCI lookaside signatures compatible with containers-registries.d.

Supported tooling¶

The signatures repository currently documents this support:

Get the StageX keyring¶

Download the keyring from the signatures repository:

curl -fsSLO https://codeberg.org/stagex/signatures/raw/branch/main/stagex-keyring.pgp

For higher assurance, compare key fingerprints against the MAINTAINERS file in the StageX source repository.

Configure lookaside signatures¶

Create ~/.config/containers/registries.d/default.yaml:

docker:
  docker.io/stagex:
    lookaside: https://sigs.stagex.tools
  quay.io/stagex:
    lookaside: https://sigs.stagex.tools

This tells compatible tooling where StageX image signatures are stored.

Add a signature policy¶

Create ~/.config/containers/policy.json and replace /path/to/stagex-keyring.pgp with the absolute path to the keyring you downloaded:

{
  "default": [
    {"type": "reject"}
  ],
  "transports": {
    "docker": {
      "docker.io/stagex": [
        {
          "type": "signedBy",
          "keyType": "GPGKeys",
          "keyPath": "/path/to/stagex-keyring.pgp",
          "signedIdentity": {
            "type": "matchRepoDigestOrExact"
          }
        }
      ],
      "quay.io/stagex": [
        {
          "type": "signedBy",
          "keyType": "GPGKeys",
          "keyPath": "/path/to/stagex-keyring.pgp",
          "signedIdentity": {
            "type": "remapIdentity",
            "prefix": "quay.io/stagex",
            "signedPrefix": "docker.io/stagex"
          }
        }
      ]
    }
  }
}

With this policy, compatible tooling rejects unsigned images by default and accepts StageX images only when signatures verify against the StageX keyring.

Historical signature notes¶

Older StageX signatures have compatibility limits:

• Signatures up to sx2025.05.2 signed the image index instead of the architecture-specific OCI manifest. They can be checked with PGP tooling, but not with lookaside policy.
• Signatures from sx2025.05.2 to sx2025.11.0 use critical.identity.docker-reference values of stagex/<package-name>, which limits signed identity policy matching for Docker Hub images.

Next steps¶

After configuring signature policy, here's what to explore next: