Releases

Active contributors: Mislav, Meredith Lancaster, Sam Coe

Purpose

gh release covers the full GitHub release surface: list, view, create, edit, delete, upload assets, download assets, and (in cooperation with gh attestation) verify SLSA provenance for releases.

Directory layout

pkg/cmd/release/
  release.go              # NewCmdRelease
  list/  view/  create/  edit/  delete/
  upload/  download/  delete-asset/
  verify/                 # gh release verify (Sigstore)
  verify-asset/           # gh release verify-asset
  attestation/            # release-specific attestation helpers
  shared/                 # asset detection, fetcher, body editing

@cli/package-security owns the verification subtree according to .github/CODEOWNERS. See Attestation for the underlying Sigstore stack.

Key abstractions

Symbol	File	Role
NewCmdRelease	pkg/cmd/release/release.go	Subcommand registration.
createRun	pkg/cmd/release/create/create.go	Largest release subcommand: tag selection, generate-notes, draft/prerelease, asset upload, discussion.
viewRun	pkg/cmd/release/view/view.go	Renders body via Glamour and lists assets.
uploadRun	pkg/cmd/release/upload/upload.go	Uploads assets to an existing release.
downloadRun	pkg/cmd/release/download/download.go	Downloads assets with optional --pattern/--archive.
verifyRun	pkg/cmd/release/verify/verify.go	Verifies attestations attached to a release.
assetType	pkg/cmd/release/shared/	MIME-type detection (uses gabriel-vasile/mimetype).

How it works

gh release create v2.99.0 --generate-notes ./gh_*.tar.gz:

1. The tag is created remotely if it does not exist; otherwise the existing tag SHA is used.
2. --generate-notes calls the REST endpoint that builds release notes from the configured release.yml template.
3. Assets are uploaded one at a time via the multipart upload endpoint, with the MIME type detected per asset.
4. If the target repo has Discussions enabled, the user can attach the release to a category.

gh release verify calls into pkg/cmd/attestation/verification with policy options derived from the release tag, repo, and signer identity.

Integration points

• Asset uploads stream from disk through pkg/iostreams for progress rendering.
• The verification subcommands embed a TUF-signed Sigstore trust root from pkg/cmd/attestation/verification/embed/.
• The release pipeline itself (.github/workflows/deployment.yml) is the producer of gh's own attestations, which makes gh release verify -R cli/cli a self-test.

Entry points for modification

• New release flag: extend release/create/create.go and update the flag-parsing test.
• New asset matcher in download: edit download.go's patterns.
• New verification policy: changes go in pkg/cmd/attestation/verification. Coordinate with the @cli/package-security team.

Key source files

File	Purpose
pkg/cmd/release/release.go	Subcommand registration.
pkg/cmd/release/create/create.go	Largest single command in this tree.
pkg/cmd/release/upload/upload.go	Asset upload flow.
pkg/cmd/release/download/download.go	Asset download with matching.
pkg/cmd/release/verify/verify.go	Sigstore verification.
pkg/cmd/release/shared/upload.go	Multipart upload helpers.
pkg/cmd/release/shared/fetch.go	Release lookup with tag name resolution.

Related pages

• Attestation for the verification stack.
• API client.