gh

README

Go library for the GitHub CLI

go-gh is a collection of Go modules to make authoring GitHub CLI extensions easier.

Modules from this library will obey GitHub CLI conventions by default:

• CurrentRepository() respects the value of the GH_REPO environment variable and reads from git remote configuration as fallback.

• GitHub API requests will be authenticated using the same mechanism as gh, i.e. using the values of GH_TOKEN and GH_HOST environment variables and falling back to the user's stored OAuth token.

• Terminal capabilities are determined by taking environment variables GH_FORCE_TTY, NO_COLOR, CLICOLOR, etc. into account.

• Generating table or Go template output uses the same engine as gh.

• The browser module activates the user's preferred web browser.

Usage

See the full go-gh reference documentation for more information

package main

import (
	"fmt"
	"log"
	"github.com/cli/go-gh"
)

func main() {
	// These examples assume `gh` is installed and has been authenticated

	// Shell out to a gh command and read its output
	issueList, _, err := gh.Exec("issue", "list", "--repo", "cli/cli", "--limit", "5")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(issueList.String())
	
	// Use an API helper to grab repository tags
	client, err := gh.RESTClient(nil)
	if err != nil {
		log.Fatal(err)
	}
	response := []struct{
		Name string
	}{}
	err = client.Get("repos/cli/cli/tags", &response)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}

See examples for more demonstrations of usage.

Contributing

If anything feels off, or if you feel that some functionality is missing, please check out our contributing docs. There you will find instructions for sharing your feedback and for submitting pull requests to the project. Thank you!

Documentation

Overview

Package gh is a library for CLI Go applications to help interface with the gh CLI tool, and the GitHub API.

Note that the examples in this package assume gh and git are installed. They do not run in the Go Playground used by pkg.go.dev.

Index

• func CurrentRepository() (repo.Repository, error)
• func Exec(args ...string) (stdOut, stdErr bytes.Buffer, err error)
• func GQLClient(opts *api.ClientOptions) (api.GQLClient, error)
• func HTTPClient(opts *api.ClientOptions) (*http.Client, error)
• func RESTClient(opts *api.ClientOptions) (api.RESTClient, error)

Examples

• CurrentRepository
• Exec
• GQLClient (Advanced)
• GQLClient (Mutate_simple)
• GQLClient (Pagination)
• GQLClient (Simple)
• RESTClient (Advanced)
• RESTClient (Pagination)
• RESTClient (Request)
• RESTClient (Simple)

Functions

func CurrentRepository

func CurrentRepository() (repo.Repository, error)

CurrentRepository uses git remotes to determine the GitHub repository the current directory is tracking.

Example

Get repository for the current directory.

package main

import (
	"fmt"
	"log"

	gh "github.com/cli/go-gh"
)

func main() {
	repo, err := gh.CurrentRepository()
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%s/%s/%s\n", repo.Host(), repo.Owner(), repo.Name())
}

func Exec

func Exec(args ...string) (stdOut, stdErr bytes.Buffer, err error)

Exec gh command with provided arguments.

Example

Execute 'gh issue list -R cli/cli', and print the output.

package main

import (
	"fmt"
	"log"

	gh "github.com/cli/go-gh"
)

func main() {
	args := []string{"issue", "list", "-R", "cli/cli"}
	stdOut, stdErr, err := gh.Exec(args...)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(stdOut.String())
	fmt.Println(stdErr.String())
}

func GQLClient

func GQLClient(opts *api.ClientOptions) (api.GQLClient, error)

GQLClient builds a client to send requests to GitHub GraphQL API endpoints. As part of the configuration a hostname, auth token, default set of headers, and unix domain socket are resolved from the gh environment configuration. These behaviors can be overridden using the opts argument.

Example (Advanced)

Query tags from cli/cli repository using GQL API. Enable caching and request timeout.

package main

import (
	"fmt"
	"log"
	"time"

	gh "github.com/cli/go-gh"
	"github.com/cli/go-gh/pkg/api"

	graphql "github.com/cli/shurcooL-graphql"
)

func main() {
	opts := api.ClientOptions{
		EnableCache: true,
		Timeout:     5 * time.Second,
	}
	client, err := gh.GQLClient(&opts)
	if err != nil {
		log.Fatal(err)
	}
	var query struct {
		Repository struct {
			Refs struct {
				Nodes []struct {
					Name string
				}
			} `graphql:"refs(refPrefix: $refPrefix, last: $last)"`
		} `graphql:"repository(owner: $owner, name: $name)"`
	}
	variables := map[string]interface{}{
		"refPrefix": graphql.String("refs/tags/"),
		"last":      graphql.Int(30),
		"owner":     graphql.String("cli"),
		"name":      graphql.String("cli"),
	}
	err = client.Query("RepositoryTags", &query, variables)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(query)
}

Example (Mutate_simple)

Add a star to the cli/go-gh repository using the GQL API.

package main

import (
	"fmt"
	"log"

	gh "github.com/cli/go-gh"
)

func main() {
	client, err := gh.GQLClient(nil)
	if err != nil {
		log.Fatal(err)
	}
	var mutation struct {
		AddStar struct {
			Starrable struct {
				Repository struct {
					StargazerCount int
				} `graphql:"... on Repository"`
				Gist struct {
					StargazerCount int
				} `graphql:"... on Gist"`
			}
		} `graphql:"addStar(input: $input)"`
	}
	// Note that the shurcooL/githubv4 package has defined input structs generated from the
	// GraphQL schema that can be used instead of writing your own.
	type AddStarInput struct {
		StarrableID string `json:"starrableId"`
	}
	variables := map[string]interface{}{
		"input": AddStarInput{
			StarrableID: "R_kgDOF_MgQQ",
		},
	}
	err = client.Mutate("AddStar", &mutation, variables)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(mutation.AddStar.Starrable.Repository.StargazerCount)
}

Example (Pagination)

Query releases from cli/cli repository using GQL API with paginated results.

package main

import (
	"fmt"
	"log"

	gh "github.com/cli/go-gh"

	graphql "github.com/cli/shurcooL-graphql"
)

func main() {
	client, err := gh.GQLClient(nil)
	if err != nil {
		log.Fatal(err)
	}
	var query struct {
		Repository struct {
			Releases struct {
				Nodes []struct {
					Name string
				}
				PageInfo struct {
					HasNextPage bool
					EndCursor   string
				}
			} `graphql:"releases(first: 30, after: $endCursor)"`
		} `graphql:"repository(owner: $owner, name: $name)"`
	}
	variables := map[string]interface{}{
		"owner":     graphql.String("cli"),
		"name":      graphql.String("cli"),
		"endCursor": (*graphql.String)(nil),
	}
	page := 1
	for {
		if err := client.Query("RepositoryReleases", &query, variables); err != nil {
			log.Fatal(err)
		}
		fmt.Printf("Page: %d\n", page)
		fmt.Println(query.Repository.Releases.Nodes)
		if !query.Repository.Releases.PageInfo.HasNextPage {
			break
		}
		variables["endCursor"] = graphql.String(query.Repository.Releases.PageInfo.EndCursor)
		page++
	}
}

Example (Simple)

Query tags from cli/cli repository using GQL API.

package main

import (
	"fmt"
	"log"

	gh "github.com/cli/go-gh"

	graphql "github.com/cli/shurcooL-graphql"
)

func main() {
	client, err := gh.GQLClient(nil)
	if err != nil {
		log.Fatal(err)
	}
	var query struct {
		Repository struct {
			Refs struct {
				Nodes []struct {
					Name string
				}
			} `graphql:"refs(refPrefix: $refPrefix, last: $last)"`
		} `graphql:"repository(owner: $owner, name: $name)"`
	}
	variables := map[string]interface{}{
		"refPrefix": graphql.String("refs/tags/"),
		"last":      graphql.Int(30),
		"owner":     graphql.String("cli"),
		"name":      graphql.String("cli"),
	}
	err = client.Query("RepositoryTags", &query, variables)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(query)
}

func HTTPClient

func HTTPClient(opts *api.ClientOptions) (*http.Client, error)

HTTPClient builds a client that can be passed to another library. As part of the configuration a hostname, auth token, default set of headers, and unix domain socket are resolved from the gh environment configuration. These behaviors can be overridden using the opts argument. In this instance providing opts.Host will not change the destination of your request as it is the responsibility of the consumer to configure this. However, if opts.Host does not match the request host, the auth token will not be added to the headers. This is to protect against the case where tokens could be sent to an arbitrary host.

func RESTClient

func RESTClient(opts *api.ClientOptions) (api.RESTClient, error)

RESTClient builds a client to send requests to GitHub REST API endpoints. As part of the configuration a hostname, auth token, default set of headers, and unix domain socket are resolved from the gh environment configuration. These behaviors can be overridden using the opts argument.

Example (Advanced)

Get tags from cli/cli repository using REST API. Specifying host, auth token, headers and logging to stdout.

package main

import (
	"fmt"
	"log"
	"os"

	gh "github.com/cli/go-gh"
	"github.com/cli/go-gh/pkg/api"
)

func main() {
	opts := api.ClientOptions{
		Host:      "github.com",
		AuthToken: "xxxxxxxxxx", // Replace with valid auth token.
		Headers:   map[string]string{"Time-Zone": "America/Los_Angeles"},
		Log:       os.Stdout,
	}
	client, err := gh.RESTClient(&opts)
	if err != nil {
		log.Fatal(err)
	}
	response := []struct{ Name string }{}
	err = client.Get("repos/cli/cli/tags", &response)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}

Example (Pagination)

Get releases from cli/cli repository using REST API with paginated results.

package main

import (
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"regexp"

	gh "github.com/cli/go-gh"
)

func main() {
	var linkRE = regexp.MustCompile(`<([^>]+)>;\s*rel="([^"]+)"`)
	findNextPage := func(response *http.Response) (string, bool) {
		for _, m := range linkRE.FindAllStringSubmatch(response.Header.Get("Link"), -1) {
			if len(m) > 2 && m[2] == "next" {
				return m[1], true
			}
		}
		return "", false
	}
	client, err := gh.RESTClient(nil)
	if err != nil {
		log.Fatal(err)
	}
	requestPath := "repos/cli/cli/releases"
	page := 1
	for {
		response, err := client.Request(http.MethodGet, requestPath, nil)
		if err != nil {
			log.Fatal(err)
		}
		data := []struct{ Name string }{}
		decoder := json.NewDecoder(response.Body)
		err = decoder.Decode(&data)
		if err != nil {
			log.Fatal(err)
		}
		if err := response.Body.Close(); err != nil {
			log.Fatal(err)
		}
		fmt.Printf("Page: %d\n", page)
		fmt.Println(data)
		var hasNextPage bool
		if requestPath, hasNextPage = findNextPage(response); !hasNextPage {
			break
		}
		page++
	}
}

Example (Request)

Get release asset from cli/cli repository using REST API.

package main

import (
	"fmt"
	"io"
	"log"
	"net/http"
	"os"

	gh "github.com/cli/go-gh"
	"github.com/cli/go-gh/pkg/api"
)

func main() {
	opts := api.ClientOptions{
		Headers: map[string]string{"Accept": "application/octet-stream"},
	}
	client, err := gh.RESTClient(&opts)
	if err != nil {
		log.Fatal(err)
	}
	// URL to cli/cli release v2.14.2 checksums.txt
	assetURL := "repos/cli/cli/releases/assets/71589494"
	response, err := client.Request(http.MethodGet, assetURL, nil)
	if err != nil {
		log.Fatal(err)
	}
	defer response.Body.Close()
	f, err := os.CreateTemp("", "*_checksums.txt")
	if err != nil {
		log.Fatal(err)
	}
	defer f.Close()
	_, err = io.Copy(f, response.Body)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("Asset downloaded to %s\n", f.Name())
}

Example (Simple)

Get tags from cli/cli repository using REST API.

package main

import (
	"fmt"
	"log"

	gh "github.com/cli/go-gh"
)

func main() {
	client, err := gh.RESTClient(nil)
	if err != nil {
		log.Fatal(err)
	}
	response := []struct{ Name string }{}
	err = client.Get("repos/cli/cli/tags", &response)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}