Development workflow

Branch and PR cycle

• The default branch is trunk, not main. PRs target trunk.
• One change per PR. Mechanical refactors should be separate PRs from feature work.
• Use the issue triage labels to surface what you are working on (the triage-pull-requests workflow auto-labels new PRs).
• Subsystem owners listed in .github/CODEOWNERS are required reviewers for their areas (Codespaces, attestation, skills, TUF root, etc.).
• The CI matrix in .github/workflows/go.yml runs unit tests on Linux, macOS, and Windows. lint.yml runs golangci-lint. govulncheck.yml runs govulncheck on every commit.

Local loop

make                       # bin/gh
go test ./...              # all unit tests
go test ./pkg/cmd/foo/...  # the area you touched
make lint                  # golangci-lint, same as CI

For acceptance tests:

go test -tags acceptance ./acceptance

For interactive smoke testing:

GH_DEBUG=api ./bin/gh issue list   # prints HTTP traffic to stderr

Commits and history

• Use descriptive commit subjects (the project's lint does not enforce conventional commits, but reviewers expect clarity).
• Squash if the PR has a noisy "fix lint", "fix test" history. Otherwise the maintainers may squash on merge.

After merge

• Releases are cut from trunk by the maintainers, not contributors. The cadence is roughly every 2-4 weeks for minor versions; patches go out on demand. See docs/release-process-deep-dive.md for the full release dance, which includes Sigstore signing and Homebrew bumping via .github/workflows/homebrew-bump.yml.
• New help text becomes manpages and the public command reference automatically: cmd/gen-docs/main.go runs as part of release and pushes to github/cli.github.com.

Working with the issue tracker

• Triage labels are managed by the workflows under .github/workflows/triage-*.yml. Spam goes through detect-spam.yml.
• Internal product partners follow docs/working-with-us.md, which describes when to file an issue, what shape proposals should take, and how triage handles new command requests.