Getting started

This page covers building cosign from source, signing your first artifact, and the most common environment knobs. For released binaries, Homebrew, the GitHub Action, and the Kubernetes installer, see docs.sigstore.dev/cosign/system_config/installation.

Prerequisites

• Go (the module declares go 1.25.7 in go.mod; the README.md quickstart says Go 1.22+ works for development).
• make for the convenience targets.
• A C toolchain only if you want PIV/Yubikey or PKCS#11 support (build tags pivkey,pkcs11key).
• Optional: Docker / ko, used by the ko-* targets in Makefile.

Clone and build

git clone https://github.com/sigstore/cosign
cd cosign
make cosign            # → ./cosign  (CGO_ENABLED=0)
./cosign version

The build plumbs git describe, the commit hash, and the build date into sigs.k8s.io/release-utils/version via -ldflags (see the LDFLAGS block at the top of the Makefile).

For hardware-token builds:

make cosign-pivkey-pkcs11key   # CGO_ENABLED=1 -tags=pivkey,pkcs11key

go install ./cmd/cosign also works and gives you a $(go env GOPATH)/bin/cosign binary.

First signature (keyless, public-good Sigstore)

# 1. Build something signable, or pick an existing image digest.
IMAGE="ghcr.io/<you>/<repo>@sha256:<digest>"

# 2. Sign. This will open a browser window for OIDC.
cosign sign $IMAGE

# 3. Verify against the identity that signed it.
cosign verify $IMAGE \
  --certificate-identity "you@example.com" \
  --certificate-oidc-issuer "https://accounts.google.com"

By default, signatures are uploaded as OCI artifacts to the same registry as the image (one tag per signed digest, see SIGNATURE_SPEC).

Always pin to @sha256:... rather than a mutable tag — the cosign sign long help (cmd/cosign/cli/sign.go) calls this out explicitly.

First signature (with a local key)

cosign generate-key-pair       # writes cosign.key (encrypted) + cosign.pub
cosign sign --key cosign.key $IMAGE
cosign verify --key cosign.pub $IMAGE

The key pair is generated by pkg/cosign/keys.go (P-256 ECDSA, scrypt-encrypted with golang.org/x/crypto/nacl/secretbox).

Useful environment variables

These are documented programmatically in pkg/cosign/env/env.go and surfaced by cosign env:

Variable	Purpose
COSIGN_PASSWORD	Password for cosign.key (skips the prompt)
COSIGN_EXPERIMENTAL	Enables in-development features
COSIGN_REPOSITORY	Override registry where signatures are stored
COSIGN_DOCKER_MEDIA_TYPES	Use legacy Docker media types for registries that reject OCI types
COSIGN_PKCS11_PIN, COSIGN_PKCS11_MODULE_PATH	PKCS#11 hardware token auth
SIGSTORE_ID_TOKEN	Pre-supplied OIDC token (skip the browser flow)
TUF_ROOT, TUF_MIRROR, TUF_ROOT_JSON	Override the TUF trust root
COSIGN_FULCIO_PRIVATE_INSTANCE, COSIGN_REKOR_PRIVATE_INSTANCE	Point at private deployments

Run cosign env for the full live list along with descriptions and current values.

Running the test suite

make test           # go test on everything except third_party/
make lint           # downloads golangci-lint v2.2.2 to ./bin and runs it
make conformance    # build the conformance binary

End-to-end tests live under test/ and assume a running registry; test/e2e_test.sh uses ghcr.io/sigstore/scaffolding for an in-cluster Sigstore stack.

Documentation regeneration

If you change a Cobra flag or add a subcommand, rebuild the markdown docs in doc/:

make docgen

This runs cmd/help/main.go, which walks the Cobra command tree and writes one cosign_<subcommand>.md per node. CI enforces that the regenerated docs are committed (see .github/workflows/verify-docgen.yaml).