Introduced in GitHub CLI 2.0, extensions allow developers to add new features by writing small Go programs. To make it easier to create extensions, GitHub is now releasing a new library, go-gh. Additionally, the latest version of GitHub CLI introduces two new commands to search and browse the catalog of available extensions.
Written in Go, the go-gh library contains portions of the code that are used in GitHub CLI itself and that GitHub hopes will help developers write high quality extensions in less time.
To create a new extension, you can use the gh ext create command. This will initialize a Go project with some boilerplate code in main.go and set it up to link against go-gh. The library provides a number of functions for common tasks, such as accessing the repository the current directory is tracking, or creating a REST, HTTP, or GraphQL client to send requests directly to GitHub APIs.
One advantage of using go-gh-provided REST, HTTP, or GraphQL clients is they will transparently use the current GitHub CLI environment configuration, thus relieving the programmer from dealing with hostname, auth token, default headers, and other requirements of using those APIs. If you need custom authentication workflows, i.e., unrelated to how the user has authenticated with GitHub CLI using git auth logon, you can do that, too.
To increase developer productivity when creating extensions, go-gh also attempts to nicely integrate with the rest of features provided by the gh command, supporting the possibility of executing existing commands. For example, this is how you would execute gh issue list -R cli/cli to capture its output in stdOut:
args := []string{"issue", "list", "-R", "cli/cli"}
stdOut, stdErr, err := gh.Exec(args...)
The gh.Exec function uses os/exec and GitHub's own safeexec behind the scene to provide the expected result.
To help developers get started with go-gh, GitHub is providing a step-by-step tutorial describing how you can select a repository, accept an argument, talk to the API, formatting the output and so on. Additionally, the official documentation provides extensive examples for each of go-gh functions.
On a related note, GitHub 2.20 introduces two new commands to make it easier for developers to discover extensions. Executing git ext browse will display a textual UI (Terminal User Interface) to list and filter extensions as well as to install or uninstall them. git ext search is the counterpart to git ext browse meant for automation and scripting. This is a traditional shell command that will output a specified number of results sorted by a given criteria. For example, this is how you can list the ten most recently updated extensions whose owner is xyz:
gh ext search --limit 10 --sort updated --owner xyz
The command can return its results as a textual table or in JSON format.
go-gh is available on GitHub.
