With the GitHub CLI, what is a gh extension, how does gh install and run one, and how do you keep it reproducible in CI?
answer
- a repository with a name prefix
- script at the root or release binaries
- arguments forwarded unchanged
- pinning to a tag or commit
- a variable that says who launched it
basics
~20 sA gh extension is a repository named gh-NAME holding an executable or release binaries; gh extension install fetches it and gh NAME runs it with your arguments. Pin it with --pin to a tag or commit so CI stays reproducible.
solid answer
~50 sAn extension is any repository whose name starts with `gh-` and that contains an executable of the same name at its root (a script extension) or precompiled binaries attached to a release, named like `gh-NAME-linux-amd64` (a binary extension). `gh extension install acme/gh-audit` looks for release binaries first and clones the repository otherwise; `gh audit ...` then runs it with every argument forwarded. Extensions cannot override core commands, run with GitHub's trust disclaimer (they are not verified or signed by GitHub) and, as of gh 2.98.0, see `GH_EXTENSION=1` in their environment. For CI, `--pin v1.4.0` (a release tag) or a commit for script extensions fixes the version; `gh extension upgrade` skips pinned extensions unless `--force`. Since gh 2.90.0 installing a public extension needs no login. `gh extension create` scaffolds a new one, with `--precompiled=go` or `--precompiled=other` for compiled languages.
code
bash · 7 lines# CI: install a reviewed release, pinned, then run it
gh extension install acme/gh-audit --pin v1.4.0
gh audit --org acme
# Development: scaffold, then install from the working directory
gh extension create --precompiled=go audit
cd gh-audit && go build && gh extension install .go deeper
Recall that an extension is a gh- prefixed repository you install with gh extension install and run as gh NAME.
Explain script against binary extensions, release-asset naming, argument forwarding and why core commands cannot be overridden.
Show how you run extensions safely in CI: reviewed source, --pin to a tag or commit, explicit installs, and knowing what GH_EXTENSION and GH_PATH give an extension at runtime.
Decide when shared team automation belongs in an owned gh extension rather than copied scripts, and who reviews and releases it.
## What an extension is A **gh extension** is a command that lives outside gh's own code. gh's help defines it as a repository that provides additional gh commands: the repository name must start with `gh-`, and the rest of the name is the command. The repository `acme/gh-audit` gives you `gh audit`. There are two kinds: | Kind | What the repository holds | How gh installs it | What `--pin` takes | |---|---|---|---| | **Script extension** | An executable file named `gh-audit` at the root (bash is the recommended interpreter) | Clones the repository | A commit | | **Binary (precompiled) extension** | Release assets named `gh-audit-OS-ARCH`, with `.exe` on Windows | Downloads the asset matching the machine | A release tag | For a remote repository gh "first looks for the release artifacts assuming that it's a binary extension" and, in the absence of a release, clones the repository as a script extension. ## Installing and running - `gh extension install acme/gh-audit` installs from github.com; a full URL such as `https://ghe.example.com/acme/gh-audit` installs from another host. - `gh extension install .` installs the extension you are developing in the current directory as a link to its executable, so an edited or rebuilt executable is picked up without reinstalling; local extensions cannot be pinned. - `gh audit --since 7d` forwards every argument to the `gh-audit` executable. - An extension **cannot override a core command**: install refuses a name that matches a built-in command or alias, and `gh extension exec NAME` runs an extension whose name later collides with one. - Extensions are installed per user on one machine; another user or machine does not have them. - `gh extension list`, `gh extension upgrade NAME` or `--all` (with `--dry-run` to preview) and `gh extension remove` manage them. When an extension runs, gh checks for a newer version once every 24 hours and prints a notice; `GH_NO_EXTENSION_UPDATE_NOTIFIER` turns that off. ## What an extension sees at runtime gh launches the executable with its own environment plus two variables: 1. `GH_EXTENSION=1`, set by gh since **2.98.0**, so the program can tell whether it was started as `gh audit` or directly. 2. `GH_PATH`, the path of the gh executable, so the extension can call back into the same gh (for example `gh api user --jq .login`) and reuse its login. A script extension is therefore often just a few `gh api` calls with argument parsing around them. ## Trust and reproducibility gh's help states that extensions "are not verified, signed, or endorsed by GitHub", a disclaimer added in **2.92.0**: installing or upgrading one means trusting its publisher, so review the source before use. In CI that leads to three habits: - **Pin** with `--pin` to a release tag (binary) or a commit (script). `gh extension upgrade` leaves a pinned extension alone and reports it; only `--force` moves it. - **Install explicitly** in the job rather than relying on whatever is on the runner. Since **2.90.0**, `gh extension install` no longer needs authentication to fetch a public extension. - **Prefer extensions your organisation owns** for anything that writes to GitHub, since they run with the job's token. ## Script or binary? - **Script extensions** are the quickest to write and read, but every user needs the interpreter; GitHub's guidance recommends bash because it is widely available. - **Precompiled extensions** need no interpreter and start fast, at the cost of a release per version with one asset per operating system and architecture you support. - The `cli/gh-extension-precompile` action can build and attach those assets from a workflow, and the `go-gh` library exposes pieces of gh's functionality to Go extensions. - Binary asset names must follow the `gh-NAME-OS-ARCH` convention (with `.exe` on Windows), because gh picks the asset by that name. ## Writing one `gh extension create audit` scaffolds a script extension; `--precompiled=go` adds Go scaffolding, workflow scaffolding and starter code, and `--precompiled=other` creates a project with a build script for another compiled language. Publishing is a repository named `gh-audit`, optionally tagged with the `gh-extension` topic so others can find it.
- Your team's extension is named gh-pr. Why does gh extension install refuse it?An extension cannot override a core gh command, and install rejects a name that matches a built-in command or alias. Rename the repository; if a later gh release adds a command with your extension's name, `gh extension exec NAME` still runs the extension.
- How does a script extension reuse the user's gh login?It calls gh itself, usually via `GH_PATH`, which gh sets to its own executable when launching extensions. Commands such as `gh api` then use whatever authentication that gh already has, so the extension never handles a token directly.
- GitHub reviews and signs extensions before they can be installed
- An extension can replace a core command such as gh pr
- gh extension upgrade --all also moves pinned extensions
- Binary extensions are built from source on the user's machine
- gh extension install always needs a logged-in gh
Assumes gh 2.102: 2.90.0 dropped the login requirement for gh extension install, 2.92.0 added the trust disclaimer to the help, and 2.98.0 began setting GH_EXTENSION=1 for extensions.