githubapp

Documentation

Overview

Package githubapp contains the data model for GitHub app installation information and GitHub app credentials.

Index

• Constants
• Variables
• func CreateCachedInstallationTokenWithDefaultOwnerRepo(ctx context.Context, settings *evergreen.Settings, lifetime time.Duration, ...) (string, error)
• func GetGitHubAppID(projectId string) (*int64, error)
• func InsertGithubAppAuth(githubAppAuth *GithubAppAuth) error
• func RemoveGithubAppAuth(id string) error
• func UpsertGithubAppAuth(githubAppAuth *GithubAppAuth) error
• type GitHubAppInstallation
  • func (h *GitHubAppInstallation) Upsert(ctx context.Context) error
• type GitHubClient
  • func (g *GitHubClient) Close()
• type GithubAppAuth
  • func CreateGitHubAppAuth(settings *evergreen.Settings) *GithubAppAuth
  • func FindOneGithubAppAuth(projectOrRepoId string) (*GithubAppAuth, error)
  • func (g *GithubAppAuth) CreateCachedInstallationToken(ctx context.Context, owner, repo string, lifetime time.Duration, ...) (string, error)
  • func (g *GithubAppAuth) CreateGitHubSenderInstallationToken(ctx context.Context, owner, repo string) (string, error)
  • func (g *GithubAppAuth) CreateInstallationToken(ctx context.Context, owner, repo string, opts *github.InstallationTokenOptions) (string, error)
  • func (g *GithubAppAuth) IsGithubAppInstalledOnRepo(ctx context.Context, owner, repo string) (bool, error)
  • func (g *GithubAppAuth) RedactPrivateKey() *GithubAppAuth

Constants

const (
	GitHubMaxRetries    = 3
	GitHubRetryMinDelay = time.Second
	GitHubRetryMaxDelay = 10 * time.Second
)

const (
	// GitHubAppAuthCollection is the name of the collection that contains
	// GitHub app auth credentials.
	GitHubAppAuthCollection = "github_app_auth"
)

const GitHubAppCollection = "github_hooks"

GitHubAppCollection contains information about Evergreen's GitHub app installations for internal use. This does not contain project-owned GitHub app credentials.

const MaxInstallationTokenLifetime = time.Hour

MaxInstallationTokenLifetime is the maximum amount of time that an installation token can be used before it expires.

Variables

var (
	GhAuthIdKey         = bsonutil.MustHaveTag(GithubAppAuth{}, "Id")
	GhAuthAppIdKey      = bsonutil.MustHaveTag(GithubAppAuth{}, "AppID")
	GhAuthPrivateKeyKey = bsonutil.MustHaveTag(GithubAppAuth{}, "PrivateKey")
)

Functions

func CreateCachedInstallationTokenWithDefaultOwnerRepo

func CreateCachedInstallationTokenWithDefaultOwnerRepo(ctx context.Context, settings *evergreen.Settings, lifetime time.Duration, opts *github.InstallationTokenOptions) (string, error)

CreateCachedInstallationTokenWithDefaultOwnerRepo is the same as CreateCachedInstallationToken but specifically returns an installation token from a default owner/repo. This is useful for scenarios when we do not care about the owner/repo that we are calling the GitHub function with (i.e. checking rate limit). It will use the default owner/repo specified in the admin settings and error if it's not set.

func GetGitHubAppID

func GetGitHubAppID(projectId string) (*int64, error)

GetGitHubAppID returns the app id for the given project id

func InsertGithubAppAuth

func InsertGithubAppAuth(githubAppAuth *GithubAppAuth) error

InsertGithubAppAuth inserts the app auth for the given project id in the database

func RemoveGithubAppAuth

func RemoveGithubAppAuth(id string) error

RemoveGithubAppAuth deletes the app auth for the given project id from the database

func UpsertGithubAppAuth

func UpsertGithubAppAuth(githubAppAuth *GithubAppAuth) error

UpsertGithubAppAuth inserts or updates the app auth for the given project id in the database

Types

type GitHubAppInstallation

type GitHubAppInstallation struct {
	Owner string `bson:"owner"`
	Repo  string `bson:"repo"`

	// InstallationID is the GitHub app's installation ID for the owner/repo.
	InstallationID int64 `bson:"installation_id"`

	// AppID is the id of the GitHub app that the installation ID is associated with
	AppID int64 `bson:"app_id"`
}

GitHubAppInstallation holds information about a GitHub app, notably its installation ID. This does not contain actual GitHub app credentials.

func (*GitHubAppInstallation) Upsert

func (h *GitHubAppInstallation) Upsert(ctx context.Context) error

Upsert updates the installation information in the database.

type GitHubClient

type GitHubClient struct {
	*github.Client
}

GitHubClient adds a Close method to the GitHub client that puts the underlying HTTP client back into the pool.

func (*GitHubClient) Close

func (g *GitHubClient) Close()

Close puts the underlying HTTP client back into the pool.

type GithubAppAuth

type GithubAppAuth struct {
	// Should match the identifier of the project it refers to
	Id string `bson:"_id" json:"_id"`

	AppID      int64  `bson:"app_id" json:"app_id"`
	PrivateKey []byte `bson:"private_key" json:"private_key"`
	// PrivateKeyParameter is the name of the parameter that holds the
	// GitHub app's private key.
	PrivateKeyParameter string `bson:"private_key_parameter" json:"private_key_parameter"`
}

GithubAppAuth holds the appId and privateKey for the github app associated with the project. It will not be stored along with the project settings, instead it is fetched only when needed Sometimes this struct is used as a way to pass around AppId and PrivateKey for Evergreen's github app, in which the Id is set to empty.

func CreateGitHubAppAuth

func CreateGitHubAppAuth(settings *evergreen.Settings) *GithubAppAuth

CreateGitHubAppAuth returns the Evergreen-internal app id and app private key if they exist. If the either are not set, it will return nil.

func FindOneGithubAppAuth

func FindOneGithubAppAuth(projectOrRepoId string) (*GithubAppAuth, error)

FindOneGithubAppAuth finds the github app auth for the given project or repo id

func (*GithubAppAuth) CreateCachedInstallationToken

func (g *GithubAppAuth) CreateCachedInstallationToken(ctx context.Context, owner, repo string, lifetime time.Duration, opts *github.InstallationTokenOptions) (string, error)

CreateCachedInstallationToken uses the owner/repo information to request an github app installation id and uses that id to create an installation token. If possible, it will try to use an existing installation token for the app from the cache, unless that cached token will expire before the requested lifetime. For example, if requesting a token that should be valid for the next 30 minutes, this method can return a cached token that is still valid for 45 minutes. However, if the cached token will expire in 5 minutes, it will provide a freshly-generated token. Also take special care if revoking a token returned from this method - revoking the token will cause other GitHub operations reusing the same token to fail.

func (*GithubAppAuth) CreateGitHubSenderInstallationToken

func (g *GithubAppAuth) CreateGitHubSenderInstallationToken(ctx context.Context, owner, repo string) (string, error)

CreateCachedInstallationTokenForGitHubSender is a helper that creates a cached installation token for the given owner/repo for the GitHub sender.

func (*GithubAppAuth) CreateInstallationToken

func (g *GithubAppAuth) CreateInstallationToken(ctx context.Context, owner, repo string, opts *github.InstallationTokenOptions) (string, error)

CreateInstallationToken creates an installation token for the given owner/repo. This is never cached, and should only be used in scenarios where the token can be revoked at any time.

func (*GithubAppAuth) IsGithubAppInstalledOnRepo

func (g *GithubAppAuth) IsGithubAppInstalledOnRepo(ctx context.Context, owner, repo string) (bool, error)

IsGithubAppInstalledOnRepo returns true if the GitHub app is installed on given owner/repo.

func (*GithubAppAuth) RedactPrivateKey

func (g *GithubAppAuth) RedactPrivateKey() *GithubAppAuth

RedactPrivateKey redacts the GitHub app's private key so that it's not exposed via the UI or GraphQL.