Getting started

This page covers how to build and run gh from source on a Unix-like system. Production install instructions live under docs/ and on cli.github.com.

Prerequisites

• Go 1.26 or newer (see go.mod).
• git 2.20 or newer on PATH (the binary shells out to git for many operations).
• make for the cross-platform build script.
• golangci-lint (matching the version pinned in .github/workflows/lint.yml) if you want to reproduce CI lint locally.

Build

make                       # Unix: invokes script/build.go and writes bin/gh
go run script/build.go     # Windows: same builder, no make required
bin/gh --version           # Smoke test

The make target delegates to script/build.go, which embeds version metadata via internal/build.

Run unit tests

go test ./...                                                 # Whole repo
go test ./pkg/cmd/issue/list/...                              # Single package
go test ./pkg/cmd/issue/list/... -run TestIssueList_nontty    # Single test

AGENTS.md is explicit: before committing, both go test ./... and make lint must pass.

Run acceptance tests

The acceptance/ tree contains end-to-end tests that exercise a real gh binary. They live behind a build tag so they do not run by default:

go test -tags acceptance ./acceptance

See acceptance/README.md for the test harness and required environment variables.

Lint

make lint                      # Same as CI: golangci-lint run ./...

The lint configuration is in .golangci.yml. It enables gofmt, goimports, staticcheck, errcheck, gosimple, gosec, misspell, and a project-specific forbidigo rule that bans the em dash character in code and comments.

Generate completions and manpages

make completions               # Writes share/{bash,zsh,fish}/...
make manpages                  # Writes share/man/man1/gh*.1

Install from source

sudo make install              # Installs gh, manpages, completions to /usr/local

For packaging details, see docs/release-process-deep-dive.md and .goreleaser.yml.

Common environment variables

Variable	Effect
GH_TOKEN / GITHUB_TOKEN	Auth token used when no gh auth login session exists.
GH_HOST	Pin the default host (e.g. for GitHub Enterprise Server).
GH_DEBUG	Verbose logging (api shows HTTP traffic).
NO_COLOR / CLICOLOR=0	Disable ANSI color output.
GH_PAGER / PAGER	Pager for long output.
GH_BROWSER / BROWSER	Browser for gh browse, web auth, etc.
GH_PROMPT_DISABLED	Force non-interactive mode.
GH_CONFIG_DIR	Override the config location (default: ~/.config/gh).

A more complete list lives in pkg/cmd/root/help_topic.go (gh help environment).

Next steps

• Development workflow: branch, code, PR, merge.
• Testing: how httpmock, iostreams.Test, and table-driven tests fit together.
• Patterns and conventions: the Options + Factory pattern enforced repo-wide.