Development workflow

The branch / PR / merge cycle for cosign tracks the upstream Sigstore process. This page lists the local commands you'll actually run.

Set up

git clone https://github.com/sigstore/cosign
cd cosign
make cosign           # build → ./cosign
./cosign version      # smoke test

go install ./cmd/cosign is also fine for local hacking.

Make a change

git checkout -b descriptive-branch-name

# edit files
make cosign           # rebuild
make test             # unit tests
make lint             # golangci-lint

If your change touches a Cobra command (in cmd/cosign/cli/), regenerate the CLI docs:

make docgen
git add doc/

CI fails fast if doc/ is out of date (see .github/workflows/verify-docgen.yaml).

Commit

git commit -s -m "subsystem: short imperative summary

Longer description if needed. Reference issue #1234."

The -s adds the DCO sign-off line, which the donotsubmit.yaml workflow checks. The conventional subject prefix is the affected subsystem (verify:, sign:, cli:, oci:, etc.) — scan git log --oneline -50 for examples.

Push and open a PR

git push -u origin descriptive-branch-name

Open the PR against main. CI will run:

• tests.yaml — unit tests on Linux/macOS/Windows for several Go versions.
• golangci-lint.yml — lint.
• e2e-tests.yml and e2e-with-binary.yml — end-to-end tests against an in-cluster Sigstore stack.
• conformance.yml and conformance-nightly.yml — sigstore-conformance integration.
• kind-verify-attestation.yaml — Kubernetes verifier integration.
• verify-docgen.yaml — re-runs make docgen and diffs.
• whitespace.yaml — trailing whitespace checks.
• depsreview.yml and codeql-analysis.yml — supply chain and static analysis.
• scorecard-action.yml — OpenSSF Scorecard run.

Iterate until everything is green and a maintainer approves.

Releases

Releases are cut by the maintainers via the cut-release.yml workflow (manual dispatch). The actual binary build/publish runs through release/ configuration and goreleaser (.goreleaser.yml). Container images go via ko (.ko.yaml). See Tooling for the moving parts.