ghinstallation
packagemodule
This package is not in the latest version of its module.
Details
Validgo.mod file
The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go.
- Redistributable license
Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed.
- Tagged version
Modules with tagged versions give importers more predictable builds.
- Stable version
When a project reaches major version v1 it is considered stable.
- Learn more about best practices
Repository
Links
Open Source Insights
README¶
ghinstallation
ghinstallation providesTransport, which implementshttp.RoundTripper toprovide authentication as an installation for GitHub Apps.
This library is designed to provide automatic authentication forhttps://github.com/google/go-github or your own HTTP client.
Installation
Get the package:
go get -u github.com/bradleyfalzon/ghinstallation/v2GitHub 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-githubclient := github.NewClient(&http.Client{Transport: itr})}You can also useNew() 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-githubclient := 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 Requesttab
WebHook request... "installation": { "id": `installation ID` }Customizing signing behavior
Users can customize signing behavior by passing in aSignerimplementation when creating anAppsTransport.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
Dependencies
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)
- type AppsTransportOption
- type Client
- type HTTPError
- type RSASigner
- type Signer
- type Transport
- 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)
Constants¶
This section is empty.
Variables¶
This section is empty.
Functions¶
funcGetReadWriter¶
func GetReadWriter(i interface{}) (io.ReadWriter,error)GetReadWriter converts a body interface into an io.ReadWriter object.
Types¶
typeAppsTransport¶
type AppsTransport struct {BaseURLstring// BaseURL is the scheme and host for GitHub API, defaults tohttps://api.github.comClientClient// 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 existinghttp.RoundTripper and provides GitHub Apps authentication as aGitHub App.
Client can also be overwritten, and is useful to change to one whichprovides retry logic if you do experience retryable errors.
funcNewAppsTransport¶
func NewAppsTransport(trhttp.RoundTripper, appIDint64, privateKey []byte) (*AppsTransport,error)
NewAppsTransport returns a AppsTransport using private key. The key is parsedand if any errors occur the error is non-nil.
The provided tr http.RoundTripper should be shared between multipleinstallations to ensure reuse of underlying TCP connections.
The returned Transport's RoundTrip method is safe to be used concurrently.
funcNewAppsTransportFromPrivateKey¶
func NewAppsTransportFromPrivateKey(trhttp.RoundTripper, appIDint64, key *rsa.PrivateKey) *AppsTransport
NewAppsTransportFromPrivateKey returns an AppsTransport using a crypto/rsa.(*PrivateKey).
funcNewAppsTransportKeyFromFile¶
func NewAppsTransportKeyFromFile(trhttp.RoundTripper, appIDint64, privateKeyFilestring) (*AppsTransport,error)
NewAppsTransportKeyFromFile returns a AppsTransport using a private key from file.
funcNewAppsTransportWithOptions¶added inv2.3.0
func NewAppsTransportWithOptions(trhttp.RoundTripper, appIDint64, opts ...AppsTransportOption) (*AppsTransport,error)
func (*AppsTransport)AppID¶added inv2.6.0
func (t *AppsTransport) AppID()int64
AppID returns the appID of the transport
typeAppsTransportOption¶added inv2.3.0
type AppsTransportOption func(*AppsTransport)
funcWithSigner¶added inv2.3.0
func WithSigner(signerSigner)AppsTransportOption
WithSigner configures the AppsTransport to use the given Signer for generating JWT tokens.
typeClient¶
Client is a HTTP client which sends a http.Request and returns a http.Responseor an error.
typeHTTPError¶
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.
typeRSASigner¶added inv2.3.0
type RSASigner struct {// contains filtered or unexported fields}RSASigner signs JWT tokens using RSA keys.
funcNewRSASigner¶added inv2.3.0
func NewRSASigner(method *jwt.SigningMethodRSA, key *rsa.PrivateKey) *RSASigner
typeSigner¶added inv2.3.0
type Signer interface {// Sign signs the given claims and returns a JWT token string, as specified// by [jwt.Token.SignedString]Sign(claimsjwt.Claims) (string,error)}Signer is a JWT token signer. This is a wrapper aroundjwt.SigningMethod with predeterminedkey material.
typeTransport¶
type Transport struct {BaseURLstring// BaseURL is the scheme and host for GitHub API, defaults tohttps://api.github.comClientClient// Client to use to refresh tokens, defaults to http.Client with provided transportInstallationTokenOptions *github.InstallationTokenOptions// parameters restrict a token's access// contains filtered or unexported fields}Transport provides a http.RoundTripper by wrapping an existinghttp.RoundTripper and provides GitHub Apps authentication as aninstallation.
Client can also be overwritten, and is useful to change to one whichprovides retry logic if you do experience retryable errors.
funcNew¶
New returns an Transport using private key. The key is parsedand if any errors occur the error is non-nil.
The provided tr http.RoundTripper should be shared between multipleinstallations to ensure reuse of underlying TCP connections.
The returned Transport's RoundTrip method is safe to be used concurrently.
funcNewFromAppsTransport¶
func NewFromAppsTransport(atr *AppsTransport, installationIDint64) *Transport
NewFromAppsTransport returns a Transport using an existing *AppsTransport.
funcNewKeyFromFile¶
func NewKeyFromFile(trhttp.RoundTripper, appID, installationIDint64, privateKeyFilestring) (*Transport,error)
NewKeyFromFile returns a Transport using a private key from file.
func (*Transport)Expiry¶added inv2.2.0
Expiry returns a transport token's expiration time and refresh time. There is a small grace periodbuilt 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¶added inv2.6.0
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.
Source Files