githubapp

Documentation

Overview

Package githubapp contains a class with methods for any service that needs to interact with GitHub as an app.

Index

• type Config
  • func NewConfig(appID, installationID string, privateKey *rsa.PrivateKey, opts ...ConfigOption) *Config
• type ConfigOption
  • func WithAccessTokenURLPattern(pattern string) ConfigOption
  • func WithHTTPClient(client *http.Client) ConfigOption
  • func WithJWTTokenCaching(beforeExp time.Duration) ConfigOption
  • func WithJWTTokenExpiration(exp time.Duration) ConfigOption
• type GitHubApp
  • func New(config *Config) *GitHubApp
  • func (g *GitHubApp) AccessToken(ctx context.Context, request *TokenRequest) (string, error)
  • func (g *GitHubApp) AccessTokenAllRepos(ctx context.Context, request *TokenRequestAllRepos) (string, error)
  • func (g *GitHubApp) AppToken() ([]byte, error)
  • func (g *GitHubApp) Token() (*oauth2.Token, error)
• type TokenRequest
• type TokenRequestAllRepos

Types

type Config

type Config struct {
	AppID          string
	InstallationID string
	PrivateKey     *rsa.PrivateKey
	// contains filtered or unexported fields
}

Config contains all of the required configuration for operating as a GitHub App. This includes the three major components, the App ID, the Install ID and the Private Key.

func NewConfig

func NewConfig(appID, installationID string, privateKey *rsa.PrivateKey, opts ...ConfigOption) *Config

NewConfig creates a new configuration object containing the three primary required configuration values. Options allow for the customization of rarely used configuration values. Options are evaluated in order from first to last.

type ConfigOption

type ConfigOption func(f *Config)

ConfigOption is a function type that applies a mechanism to set optional configuration values.

func WithAccessTokenURLPattern

func WithAccessTokenURLPattern(pattern string) ConfigOption

WithAccessTokenURLPattern allows overriding of the GitHub api url that is used when generating installation access tokens. The default is the primary GitHub api url which should only be overridden for private GitHub installations.

The `pattern` parameter expects a single `%s` that represents the installation id that is provided with the rest of the configuration.

func WithHTTPClient

func WithHTTPClient(client *http.Client) ConfigOption

WithHTTPClient is an option that allows a consumer to provider their own http client implementation.

func WithJWTTokenCaching

func WithJWTTokenCaching(beforeExp time.Duration) ConfigOption

WithJWTTokenCaching is an option that tells the GitHub app to cache its JWT App tokens. The amount of time that the tokens are cached is based on the provided `beforeExp` parameter + the configured token expiration. This results in a cache expiration of <token expiration> - <beforeExp>.

func WithJWTTokenExpiration

func WithJWTTokenExpiration(exp time.Duration) ConfigOption

WithJWTTokenExpiration is an option that allows overriding the default expiration date of the application JWTs.

type GitHubApp

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

GitHubApp is an object that can be used to generate application level JWTs or to request an OIDC token on behalf of an installation.

func New

func New(config *Config) *GitHubApp

New creates a GitHubApp instance based on the provided GitHubAppConfig object.

func (*GitHubApp) AccessToken

func (g *GitHubApp) AccessToken(ctx context.Context, request *TokenRequest) (string, error)

AccessToken calls the GitHub API to generate a new access token for this application installation with the requested permissions and repositories.

func (*GitHubApp) AccessTokenAllRepos

func (g *GitHubApp) AccessTokenAllRepos(ctx context.Context, request *TokenRequestAllRepos) (string, error)

AccessTokenAllRepos calls the GitHub API to generate a new access token for this application installation with the requested permissions and all granted repositories.

func (*GitHubApp) AppToken

func (g *GitHubApp) AppToken() ([]byte, error)

AppToken creates a signed JWT to authenticate a GitHub app so that it can make API calls to GitHub.

func (*GitHubApp) Token

func (g *GitHubApp) Token() (*oauth2.Token, error)

Token adheres to the oauth2 TokenSource interface and returns a oauth2 token by creating a JWT token.

type TokenRequest

type TokenRequest struct {
	Repositories []string          `json:"repositories"`
	Permissions  map[string]string `json:"permissions"`
}

TokenRequest is a struct that contains the list of repositories and the requested permissions / scopes that are requested when generating a new installation access token.

type TokenRequestAllRepos

type TokenRequestAllRepos struct {
	Permissions map[string]string `json:"permissions"`
}

TokenRequestAllRepos is a struct that contains the requested permissions/scopes that are requested when generating a new installation access token. This struct intentionally omits the repository properties to generate a token for all repositories granted to this GitHub app installation.