All jobs

Sign Docker Images with Cosign in CI

Yes. An agent adds keyless cosign signing of your multi-arch image digest to the publish workflow, writes the verify command, tests it in its sandbox and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent clones the repository into its own cloud sandbox and reads how the image is built and pushed today. In a project like umputun/remark42, the root Dockerfile is a four-stage build, node:24-alpine for the frontend, umputun/baseimage:buildgo for the Go backend with the tests run inside the build unless SKIP_BACKEND_TEST is set, and a final umputun/baseimage:app stage with OCI labels, a HEALTHCHECK on /ping and EXPOSE 8080; .dockerignore is a whitelist. .github/workflows/docker.yml runs on workflow_run after the backend and frontend workflows succeed on master or a v* tag, builds linux/amd64 on ubuntu-latest and linux/arm64 on an arm runner, pushes each platform image by digest to ghcr.io/umputun/remark42 and umputun/remark42 with push-by-digest=true, uploads the digests as artifacts, and a merge job runs docker buildx imagetools create to publish the multi-arch manifest under the branch tag and latest. The job's permissions are contents: read and packages: write. Nothing is signed, attested or verifiable: a consumer pulling latest has only the registry's word for where it came from.

It adds signing to the merge job, because that is where the final digest exists. The job gains id-token: write so GitHub issues an OIDC token, and sigstore/cosign-installer pinned to a release. After each imagetools create, a step reads the manifest list digest back with docker buildx imagetools inspect <image>:<tag> --format '{{json .Manifest.Digest}}', and runs cosign sign --yes <image>@<digest> for the GHCR image and for the Docker Hub image. Signing by digest rather than by tag is the point: latest moves, the digest does not, and the signature attaches to the content. Keyless mode means there is no private key to store or rotate; the signature is bound to a short-lived certificate naming this repository and this workflow file, recorded in the public transparency log. The two registry logins the job already performs are enough, since cosign stores the signature as an OCI artifact next to the image.

Signing the index is not the same as signing each platform image, so the agent also signs the per-platform digests the build job uploaded as artifacts, which the merge job already downloads to assemble the manifest. A consumer who pulls on an arm64 machine resolves to the platform manifest, and cosign verify of that digest should succeed as well. The agent writes a page under docs/ with the exact cosign verify command, including --certificate-identity-regexp for the workflow path on this repository and --certificate-oidc-issuer for GitHub Actions, and a docker-compose.yml comment pointing at it, because a signature nobody knows how to check protects nobody.

It proves the mechanism in its sandbox before opening anything. The sandbox has no Docker, so it installs it with sudo apt-get install -y docker.io, starts dockerd, runs a local registry:2 container, pushes a small image to it, resolves its digest, and runs cosign sign --key with a throwaway key pair and cosign verify --key against that digest, which exercises every command in the new steps apart from the OIDC exchange that only exists inside GitHub Actions. It runs actionlint on the changed workflow and pastes the outputs into the pull request, with a note that the first real signature appears on the next push to master.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add cosign image signing to this project's Docker publish workflow. Read the Dockerfile, .dockerignore, the Makefile docker targets and every workflow under .github/workflows first, and describe how images are built, pushed and tagged today, including whether the multi-arch manifest is assembled in a separate job. In the job that publishes the final manifest, add the id-token write permission and the cosign installer, read back the manifest list digest for each registry after it is created, and sign that digest keyless with cosign; also sign the per-platform digests the job already has. Do not add a stored signing key. Write a docs page with the exact cosign verify command for this repository and workflow, and link it from the compose file. In your sandbox install Docker, start a local registry, push a small image, sign and verify it by digest with a throwaway key pair to exercise the commands, run actionlint, and open a pull request with the workflow diff, the docs page and the command output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

What comes back is a pull request changing .github/workflows/docker.yml, adding one permission, the installer step and the sign steps after each imagetools create, plus a new page under docs/ with the verify command and a one-line pointer in docker-compose.yml. The Dockerfile, the build job and the tags are unchanged. The description explains why the index digest and the platform digests are both signed and what identity the certificate will carry.

The run's record keeps the local registry session: the push, the digest, cosign sign and cosign verify succeeding against it, and the actionlint output. A reviewer sees the commands work end to end, and knows the only untested piece is the OIDC token GitHub supplies at run time.

Before merging, a reviewer checks that the organisation allows id-token: write on workflows, decides whether to also sign the before and after tags the Docker Hub rules publish, and schedules a look at the first master build to run the documented cosign verify once against the published image.

Run it on every new image repository

A platform engineer hands this off from the terminal once per project: one POST /o/{org}/sessions with this body and the repository in resources. For a dozen services that publish images, a script sends one request per repository, each with a request_id that is a UUID v5 of the repository name so a rerun returns the run it already started, and the key's webhook_url reports each finished run with its pull request.

Every run reads that repository's own workflow first, since the job that holds the final digest differs between a single build-push-action step and a build-then-merge layout like this one, and puts the signing step where that project's digest actually is.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

Image signing fails quietly when it is done in the wrong job or against a tag instead of a digest. Reading the workflow first, finding the step where the multi-arch manifest is created, and signing the digest it returns is the whole job; the sandbox is where the agent can stand up a registry and run the exact commands against a real digest before they are committed, so the pull request is a diff plus a log rather than a diff plus hope.

The same body runs across every service an organisation ships as an image, and each pull request keeps its own record and its own verify command. A security team then has one documented way to check provenance for every image, written per repository by something that read that repository.

Frequently asked questions

Where is the signing key stored?

Nowhere. Keyless signing uses a certificate issued for the workflow run from GitHub's OIDC token, valid for minutes, and the signature plus certificate are recorded in the Sigstore transparency log. There is no secret to rotate and no key to leak; a consumer checks the certificate identity instead.

Why sign the digest and not the tag?

A tag like latest is a pointer that moves with every push; a digest is the content. Signing by digest means the signature follows the exact bytes wherever they are retagged, and cosign verify of a tag resolves it to the digest first, so consumers can still verify by tag.

Does it work with workflow_run triggers?

Yes. The OIDC token is available to any workflow with id-token: write, and the certificate identity names the workflow file and ref that ran. The verify command in the docs uses a regular expression on that identity so it matches signatures from master and from v* tags.

Does the sandbox actually push to our registries?

No. It pushes to a local registry:2 container it starts itself, signs and verifies there with a throwaway key, and discards it. The keyless path against GHCR and Docker Hub runs for the first time on the next push to master, which the pull request says to check.

What about SBOMs and build provenance?

Signing is the first step and the pull request stops there. Attaching an SBOM with cosign attest or enabling provenance attestations in build-push-action are the natural follow-ups, and the docs page lists both with the verify flags they would need.

More Docker jobs

More jobs like this: Hand off a long task

Keep reading