github

Documentation

Overview

Package github provides high-level functions that are called from the Go Bonzai branch of the same name providing universal access to the core functionality. Use of interfaces over structs with public properties is to allow the gradual addition of useful data from the underlying JSON structs.

Index

• Variables
• func Latest(id string) (string, error)
• func NewClient() *client
• func Repo(id string) (map[string]any, error)
• type Client

Examples

• Client (Defaults)
• Latest
• Repo

Variables

var APIVersion = "v3"

APIVersion is the default used when returning the API.

var DefaultClient = NewClient()

var Host = "github.com"

Host specifies the host to use for all GitHub web requests. It is the public "github.com" by default. Anything else will trigger GitHub Enterprise assumptions. This is overridden at init() by the GH_HOST environment variable consistent with the official GitHub CLI tool.

Functions

func Latest

func Latest(id string) (string, error)

Example

package main

import (
	"fmt"

	"github.com/rwxrob/bonzai/github"
)

func main() {
	ver, err := github.Latest(`docker/compose`)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(ver[0:2])
}

Output:

v2

func NewClient

func NewClient() *client

NewClient returns a new struct pointer fulfilling the Client interface.

func Repo

func Repo(id string) (map[string]any, error)

Example

package main

import (
	"fmt"

	"github.com/rwxrob/bonzai/github"
)

func main() {
	repo, err := github.Repo(`rwxrob/z`)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(repo["name"])
}

Output:

z

Types

type Client

type Client interface {

	// Host of github.com (the default
	Host() string
	SetHost(a string)
	APIVersion() string
	SetAPIVersion(a string)
	Repo(id string) (map[string]any, error)

	// API returns a full URL string for the given Host based on
	// inferred usage of GitHub Enterprise:
	//
	//     Host == github.com         -> https://api.github.com/
	//     Host == github.example.com -> https://github.example.com/api/v3
	//
	API() string
}

Client specified a GitHub client capable of returned a limited number of data points from the API. This interface will grow as the struct returned by NewClient sufficiently adds new, common queries.

Public Versus Enterprise

It's not particularly well-known, but the API queries for both public GitHub and GitHub Enterprise differ primarily only in the host and URL that is used. GitHub Enterprise requires a token with more permissions than is permitted by GitHub public API as well.

github.com (public)
github.example.com (enterprise)

Example (Defaults)

package main

import (
	"fmt"

	"github.com/rwxrob/bonzai/github"
)

func main() {
	gh := github.NewClient()
	fmt.Println(gh.Host())
	fmt.Println(gh.APIVersion())
	fmt.Println(gh.API(`rwxrob/web`))
}

Output:

github.com
v3
https://api.github.com/rwxrob/web