Tooling

The tooling pipeline is small but opinionated.

Build

• Makefile is the developer entry point. It delegates to script/build.go so the same code path runs on Unix and Windows.
• bin/gh is the canonical output. The script embeds version and build date metadata via internal/build.
• make completions regenerates shell completions into share/{bash,zsh,fish}/. make manpages regenerates man pages from the embedded help text.
• make install installs gh, the manpages, and the completions into a Unix prefix (defaults to /usr/local).

Lint

• make lint runs golangci-lint run ./....
• Configuration lives in .golangci.yml. Enabled linters include gofmt, goimports, staticcheck, errcheck, gosec, misspell, and forbidigo. The forbidigo rule bans em dashes.
• lint.yml (.github/workflows/) re-runs the same configuration in CI.

Code generation

• Mocks are generated by moq and committed (e.g. internal/prompter/prompter_mock.go, pkg/cmd/codespace/mock_api.go).
• The Twirp telemetry client at internal/barista/observability/telemetry.twirp.go is generated from the corresponding .proto.
• Run go generate ./... after touching any interface that has a //go:generate moq ... directive.

Documentation generation

• cmd/gen-docs/main.go walks the Cobra tree and writes per-command Markdown plus manpages. The Makefile uses it for make manpages and the release pipeline uses it to refresh cli.github.com/manual/.
• gh help reference produces a single paged document via the same machinery (pkg/cmd/root/help_reference.go).

CI workflows

Workflow	What it does
go.yml	Unit tests on Linux, macOS, Windows.
lint.yml	golangci-lint.
govulncheck.yml	Vulnerability scan against vulndb.
codeql.yml	GitHub CodeQL static analysis.
deployment.yml	GoReleaser, Sigstore signing, SLSA attestation, package builds.
bump-go.yml	Periodic dependency bump for the Go toolchain.
homebrew-bump.yml	Bumps the Homebrew formula on release.
triage-*.yml	Issue and PR triage automation.
detect-spam.yml	Auto-flags spam content.

Release packaging

• .goreleaser.yml defines per-OS archives, RPM/DEB/MSI builders, and homebrew bottle metadata.
• script/release and script/pkgmacos build local release artefacts. make macospkg VERSION=vX.Y.Z produces a signed .pkg.
• script/licenses (and the corresponding licenses-check target) regenerate the license-attribution database under internal/licenses/.

Acceptance harness

• The acceptance/ tree builds against a real gh binary using a Go test runner. It is gated behind -tags acceptance so a stray go test ./... does not pull network or credentials. See acceptance/README.md for prerequisites.

Internal scripts

• script/ contains release helpers (release, release-deb, release-rpm, release-msi, pkgmacos), licenses, the build.go cross-platform builder, and a few CI helpers. They are intentionally Go programs where possible so they run identically on every supported OS.