Extensions

Active contributors: vilmibm, Sam Coe, Mislav

Purpose

gh extension is gh's package manager. It lets users install third-party gh-<name> commands as scripts, precompiled binaries, or Go source trees, then exposes them as native subcommands. The framework also supports browsing, searching, upgrading, listing, removing, executing, and developer-mode (gh extension exec and gh extension create).

Directory layout

pkg/cmd/extension/
  extension.go              # NewCmdExtension: registers subcommands
  command.go                # ~24 KB: the verb dispatcher (install, list, ...)
  manager.go                # ~24 KB: install/upgrade/list/remove machinery
  http.go                   # GitHub releases lookup for binary extensions
  git.go                    # git operations for script extensions
  browse/                   # gh extension browse: TUI for the registry
  ext_tmpls/                # scaffolding for gh extension create
  mocks.go                  # exported mock for downstream tests
  symlink_other.go / symlink_windows.go  # platform-specific symlinks

The extension manager is consumed by pkg/cmd/factory/default.go so extensions are discovered at startup, then injected into the root command in pkg/cmd/root/root.go.

Key abstractions

Symbol	File	Role
Manager	manager.go	The interface implemented by extension.Manager. Lifecycle: List, Install, Upgrade, Remove, Dispatch, Create.
Extension	pkg/extensions/extension.go	Abstract description of an installed extension.
binaryExtension / gitExtension	manager.go	Variants for precompiled binaries vs cloned scripts.
OfficialExtensions	pkg/extensions/official.go	Curated list of GitHub-owned extensions used by stub registration.
NewCmdOfficialExtensionStub	pkg/cmd/root/official_extension_stub.go	Hidden Cobra command that prompts the user to install a stub-only extension when invoked.
BrowseTUI	pkg/cmd/extension/browse/browse.go	tview-based TUI for searching the extension registry.

How it works

graph TD
    A[Root command startup] --> B[factory.New]
    B --> C[extension.NewManager]
    C --> D[Manager.List discovers ~/.local/share/gh/extensions/*]
    A --> E[root.NewCmdRoot adds discovered extensions]
    E --> F[name collision with core command? skip]
    E --> G[Cobra registers gh-<name> as a subcommand]
    G -->|invoked| H[Manager.Dispatch runs the underlying script/binary]
    A --> I[OfficialExtensions stubs registered AFTER real extensions]

Three install styles are supported:

1. Script - clone the repo, expect a gh-<name> shell script at the root.
2. Binary - look up the latest GitHub release, match OS-ARCH, and unpack a compiled binary.
3. Go source - compile from source with go build.

gh extension upgrade --all walks the install tree and refreshes each extension by its declared mechanism. The "Upgrade available" hint at startup is rate-limited to avoid hammering the GitHub API.

Integration points

• Read by factory.New and stored on cmdutil.Factory.ExtensionManager. Surface area for tests is via pkg/cmd/extension/mocks.go.
• Talks to GitHub directly via http.go to look up release assets.
• The "official extension stubs" mechanism is a UX layer that suggests installing first-party extensions when a user invokes a name like gh copilot (when not yet installed).

Entry points for modification

• New extension type: extend manager.go with a new variant of Extension plus its install/upgrade/dispatch logic. Update tests in manager_test.go (~47 KB).
• New CLI verb on gh extension: add the function in command.go, register it in extension.go.
• Changing the official stub list: edit pkg/extensions/official.go. New entries automatically get hidden Cobra commands.

Key source files

File	Purpose
pkg/cmd/extension/extension.go	Subcommand registration.
pkg/cmd/extension/command.go	Verb dispatcher.
pkg/cmd/extension/manager.go	Install / upgrade / dispatch / list.
pkg/cmd/extension/http.go	Release lookup for binary extensions.
pkg/cmd/extension/git.go	Git operations for script extensions.
pkg/cmd/extension/browse/browse.go	tview-based browse TUI.
pkg/cmd/extension/ext_tmpls/	Templates for gh extension create.
pkg/cmd/root/official_extension_stub.go	Stubs for unstalled official extensions.

Related pages

• Extension manager (system view).
• Patterns and conventions.