gh

README

go-gh

A Go module for CLI Go applications and gh extensions that want a convenient way to interact with gh, and the GitHub API using gh environment configuration.

Installation

go get https://github.com/cli/go-gh

Usage

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

// Execute `gh issue list -R cli/cli`, and print the output.
func main() {
	args := []string{"issue", "list", "-R", "cli/cli"}
	stdOut, stdErr, err := gh.Exec(args...)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(stdOut.String())
	fmt.Println(stdErr.String())
}

See examples for more use cases.

Contributing

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

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 Exec(args ...string) (stdOut, stdErr bytes.Buffer, err error)
• func GQLClient(opts *api.ClientOptions) (api.GQLClient, error)
• func RESTClient(opts *api.ClientOptions) (api.RESTClient, error)
• type Repository
  • func CurrentRepository() (Repository, error)

Examples

• CurrentRepository
• Exec
• GQLClient (Advanced)
• GQLClient (Simple)
• RESTClient (Advanced)
• RESTClient (Simple)

Functions

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.

args := []string{"issue", "list", "-R", "cli/cli"}
stdOut, stdErr, err := 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, and default set of headers 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.

opts := api.ClientOptions{
	EnableCache: true,
	Timeout:     5 * time.Second,
}
client, err := 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 (Simple)

Query tags from cli/cli repository using GQL API.

client, err := 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 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, and default set of headers 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.

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 := 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 (Simple)

Get tags from cli/cli repository using REST API.

client, err := 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)

Types

type Repository

type Repository interface {
	Host() string
	Name() string
	Owner() string
}

Repository is the interface that wraps repository information methods.

func CurrentRepository

func CurrentRepository() (Repository, error)

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

Example

Get repository for the current directory.

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