ghinstallation

README

ghinstallation

ghinstallation provides Transport, which implements http.RoundTripper to provide authentication as an installation for GitHub Apps.

This library is designed to provide automatic authentication for https://github.com/google/go-github or your own HTTP client.

See https://developer.github.com/apps/building-integrations/setting-up-and-registering-github-apps/about-authentication-options-for-github-apps/

Example

Get the package:

go get -u github.com/bradleyfalzon/ghinstallation

Usage:

import "github.com/bradleyfalzon/ghinstallation"

func main() {
    // Shared transport to reuse TCP connections.
    tr := http.DefaultTransport

    // Wrap the shared transport for use with the integration ID 1 authenticating with installation ID 99.
    itr, err := ghinstallation.NewKeyFromFile(tr, 1, 99, "2016-10-19.private-key.pem")
    if err != nil {
        log.Fatal(err)
    }

    // Use installation transport with github.com/google/go-github
    client := github.NewClient(&http.Client{Transport: itr})
}

License

Unlicense - feel free to copy/paste without attribution/preservation of license etc.

Dependencies

• github.com/dgrijalva/jwt-go

Documentation

Index

• type AppsTransport
  • func NewAppsTransport(tr http.RoundTripper, integrationID int, privateKey []byte) (*AppsTransport, error)
  • func NewAppsTransportKeyFromFile(tr http.RoundTripper, integrationID int, privateKeyFile string) (*AppsTransport, error)
  • func (t *AppsTransport) RoundTrip(req *http.Request) (*http.Response, error)
• type Client
• type Transport
  • func New(tr http.RoundTripper, integrationID, installationID int, privateKey []byte) (*Transport, error)
  • func NewKeyFromFile(tr http.RoundTripper, integrationID, installationID int, privateKeyFile string) (*Transport, error)
  • func (t *Transport) RoundTrip(req *http.Request) (*http.Response, error)
  • func (t *Transport) Token() (string, error)

Types

type AppsTransport

type AppsTransport struct {
	BaseURL string // BaseURL is the scheme and host for GitHub API, defaults to https://api.github.com
	Client  Client // Client to use to refresh tokens, defaults to http.Client with provided transport
	// contains filtered or unexported fields
}

AppsTransport provides a http.RoundTripper by wrapping an existing http.RoundTripper and provides GitHub Apps authentication as a GitHub App.

Client can also be overwritten, and is useful to change to one which provides retry logic if you do experience retryable errors.

See https://developer.github.com/apps/building-integrations/setting-up-and-registering-github-apps/about-authentication-options-for-github-apps/

func NewAppsTransport

func NewAppsTransport(tr http.RoundTripper, integrationID int, privateKey []byte) (*AppsTransport, error)

NewAppsTransport returns a AppsTransport using private key. The key is parsed and if any errors occur the error is non-nil.

The provided tr http.RoundTripper should be shared between multiple installations to ensure reuse of underlying TCP connections.

The returned Transport's RoundTrip method is safe to be used concurrently.

func NewAppsTransportKeyFromFile

func NewAppsTransportKeyFromFile(tr http.RoundTripper, integrationID int, privateKeyFile string) (*AppsTransport, error)

NewAppsTransportKeyFromFile returns a AppsTransport using a private key from file.

func (*AppsTransport) RoundTrip

func (t *AppsTransport) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip implements http.RoundTripper interface.

type Client

type Client interface {
	Do(*http.Request) (*http.Response, error)
}

Client is a HTTP client which sends a http.Request and returns a http.Response or an error.

type Transport

type Transport struct {
	BaseURL string // BaseURL is the scheme and host for GitHub API, defaults to https://api.github.com
	Client  Client // Client to use to refresh tokens, defaults to http.Client with provided transport
	// contains filtered or unexported fields
}

Transport provides a http.RoundTripper by wrapping an existing http.RoundTripper and provides GitHub Apps authentication as an installation.

Client can also be overwritten, and is useful to change to one which provides retry logic if you do experience retryable errors.

See https://developer.github.com/apps/building-integrations/setting-up-and-registering-github-apps/about-authentication-options-for-github-apps/

func New

func New(tr http.RoundTripper, integrationID, installationID int, privateKey []byte) (*Transport, error)

New returns an Transport using private key. The key is parsed and if any errors occur the error is non-nil.

The provided tr http.RoundTripper should be shared between multiple installations to ensure reuse of underlying TCP connections.

The returned Transport's RoundTrip method is safe to be used concurrently.

func NewKeyFromFile

func NewKeyFromFile(tr http.RoundTripper, integrationID, installationID int, privateKeyFile string) (*Transport, error)

NewKeyFromFile returns a Transport using a private key from file.

func (*Transport) RoundTrip

func (t *Transport) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip implements http.RoundTripper interface.

func (*Transport) Token

func (t *Transport) Token() (string, error)

Token checks the active token expiration and renews if necessary. Token returns a valid access token. If renewal fails an error is returned.