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/

Installation

Get the package:

GO111MODULE=on go get -u github.com/bradleyfalzon/ghinstallation/v2

GitHub Example

import "github.com/bradleyfalzon/ghinstallation/v2"

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

    // Wrap the shared transport for use with the app 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})
}

You can also use New() to load a key directly from a []byte.

GitHub Enterprise Example

For clients using GitHub Enterprise, set the base URL as follows:

import "github.com/bradleyfalzon/ghinstallation/v2"

const GitHubEnterpriseURL = "https://github.example.com/api/v3"

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

    // Wrap the shared transport for use with the app 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)
    }
    itr.BaseURL = GitHubEnterpriseURL

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

What is app ID and installation ID

app ID is the GitHub App ID.
You can check as following :
Settings > Developer > settings > GitHub App > About item

installation ID is a part of WebHook request.
You can get the number to check the request.
Settings > Developer > settings > GitHub Apps > Advanced > Payload in Request tab

WebHook request
...
  "installation": {
    "id": `installation ID`
  }

Customizing signing behavior

Users can customize signing behavior by passing in a Signer implementation when creating an AppsTransport. For example, this can be used to create tokens backed by keys in a KMS system.

signer := &myCustomSigner{
  key: "https://url/to/key/vault",
}
atr := NewAppsTransportWithOptions(http.DefaultTransport, 1, WithSigner(signer))
tr := NewFromAppsTransport(atr, 99)

License

Apache 2.0

Dependencies

• github.com/golang-jwt/jwt-go

Documentation

Index

• func GetReadWriter(i interface{}) (io.ReadWriter, error)
• type AppsTransport
  • func NewAppsTransport(tr http.RoundTripper, appID int64, privateKey []byte) (*AppsTransport, error)
  • func NewAppsTransportFromPrivateKey(tr http.RoundTripper, appID int64, key *rsa.PrivateKey) *AppsTransport
  • func NewAppsTransportKeyFromFile(tr http.RoundTripper, appID int64, privateKeyFile string) (*AppsTransport, error)
  • func NewAppsTransportWithOptions(tr http.RoundTripper, appID int64, opts ...AppsTransportOption) (*AppsTransport, error)
  • func (t *AppsTransport) AppID() int64
  • func (t *AppsTransport) RoundTrip(req *http.Request) (*http.Response, error)
• type AppsTransportOption
  • func WithSigner(signer Signer) AppsTransportOption
• type Client
• type HTTPError
  • func (e *HTTPError) Error() string
  • func (e *HTTPError) Unwrap() error
• type RSASigner
  • func NewRSASigner(method *jwt.SigningMethodRSA, key *rsa.PrivateKey) *RSASigner
  • func (s *RSASigner) Sign(claims jwt.Claims) (string, error)
• type Signer
• type Transport
  • func New(tr http.RoundTripper, appID, installationID int64, privateKey []byte) (*Transport, error)
  • func NewFromAppsTransport(atr *AppsTransport, installationID int64) *Transport
  • func NewKeyFromFile(tr http.RoundTripper, appID, installationID int64, privateKeyFile string) (*Transport, error)
  • func (t *Transport) AppID() int64
  • func (t *Transport) Expiry() (expiresAt time.Time, refreshAt time.Time, err error)
  • func (t *Transport) InstallationID() int64
  • func (t *Transport) Permissions() (github.InstallationPermissions, error)
  • func (t *Transport) Repositories() ([]github.Repository, error)
  • func (t *Transport) RoundTrip(req *http.Request) (*http.Response, error)
  • func (t *Transport) Token(ctx context.Context) (string, error)

Functions

func GetReadWriter

func GetReadWriter(i interface{}) (io.ReadWriter, error)

GetReadWriter converts a body interface into an io.ReadWriter object.

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, appID int64, 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 NewAppsTransportFromPrivateKey

func NewAppsTransportFromPrivateKey(tr http.RoundTripper, appID int64, key *rsa.PrivateKey) *AppsTransport

NewAppsTransportFromPrivateKey returns an AppsTransport using a crypto/rsa.(*PrivateKey).

func NewAppsTransportKeyFromFile

func NewAppsTransportKeyFromFile(tr http.RoundTripper, appID int64, privateKeyFile string) (*AppsTransport, error)

NewAppsTransportKeyFromFile returns a AppsTransport using a private key from file.

func NewAppsTransportWithOptions

func NewAppsTransportWithOptions(tr http.RoundTripper, appID int64, opts ...AppsTransportOption) (*AppsTransport, error)

func (*AppsTransport) AppID

func (t *AppsTransport) AppID() int64

AppID returns the appID of the transport

func (*AppsTransport) RoundTrip

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

RoundTrip implements http.RoundTripper interface.

type AppsTransportOption

type AppsTransportOption func(*AppsTransport)

func WithSigner

func WithSigner(signer Signer) AppsTransportOption

WithSigner configures the AppsTransport to use the given Signer for generating JWT tokens.

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 HTTPError

type HTTPError struct {
	Message        string
	RootCause      error
	InstallationID int64
	Response       *http.Response
}

HTTPError represents a custom error for failing HTTP operations. Example in our usecase: refresh access token operation. It enables the caller to inspect the root cause and response.

func (*HTTPError) Error

func (e *HTTPError) Error() string

func (*HTTPError) Unwrap

func (e *HTTPError) Unwrap() error

Unwrap implements the standard library's error wrapping. It unwraps to the root cause.

type RSASigner

type RSASigner struct {
	// contains filtered or unexported fields
}

RSASigner signs JWT tokens using RSA keys.

func NewRSASigner

func NewRSASigner(method *jwt.SigningMethodRSA, key *rsa.PrivateKey) *RSASigner

func (*RSASigner) Sign

func (s *RSASigner) Sign(claims jwt.Claims) (string, error)

Sign signs the JWT claims with the RSA key.

type Signer

type Signer interface {
	// Sign signs the given claims and returns a JWT token string, as specified
	// by [jwt.Token.SignedString]
	Sign(claims jwt.Claims) (string, error)
}

Signer is a JWT token signer. This is a wrapper around jwt.SigningMethod with predetermined key material.

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

	InstallationTokenOptions *github.InstallationTokenOptions // parameters restrict a token's access
	// 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, appID, installationID int64, 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 NewFromAppsTransport

func NewFromAppsTransport(atr *AppsTransport, installationID int64) *Transport

NewFromAppsTransport returns a Transport using an existing *AppsTransport.

func NewKeyFromFile

func NewKeyFromFile(tr http.RoundTripper, appID, installationID int64, privateKeyFile string) (*Transport, error)

NewKeyFromFile returns a Transport using a private key from file.

func (*Transport) AppID

func (t *Transport) AppID() int64

AppID returns the app ID associated with the transport

func (*Transport) Expiry

func (t *Transport) Expiry() (expiresAt time.Time, refreshAt time.Time, err error)

Expiry returns a transport token's expiration time and refresh time. There is a small grace period built in where a token will be refreshed before it expires. expiresAt is the actual token expiry, and refreshAt is when a call to Token() will cause it to be refreshed.

func (*Transport) InstallationID

func (t *Transport) InstallationID() int64

InstallationID returns the installation ID associated with the transport

func (*Transport) Permissions

func (t *Transport) Permissions() (github.InstallationPermissions, error)

Permissions returns a transport token's GitHub installation permissions.

func (*Transport) Repositories

func (t *Transport) Repositories() ([]github.Repository, error)

Repositories returns a transport token's GitHub repositories.

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(ctx context.Context) (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.