common

Documentation

Index

• Constants
• type GithubClient
• type GithubEnterpriseClient
• type OrganizationHooks
• type PoolManager
• type Provider
• type RepositoryHooks

Constants

const (
	PoolScaleDownInterval     = 1 * time.Minute
	PoolConsilitationInterval = 5 * time.Second
	PoolReapTimeoutInterval   = 5 * time.Minute
	// Temporary tools download token is valid for 1 hour by default.
	// There is no point in making an API call to get available tools, for every runner
	// we spin up. We cache the tools for 5 minutes. This should save us a lot of API calls
	// in cases where we have a lot of runners spin up at the same time.
	PoolToolUpdateInterval = 5 * time.Minute

	// BackoffTimer is the time we wait before attempting to make another request
	// to the github API.
	BackoffTimer = 1 * time.Minute
)

Types

type GithubClient

type GithubClient interface {
	OrganizationHooks
	RepositoryHooks

	// GetWorkflowJobByID gets details about a single workflow job.
	GetWorkflowJobByID(ctx context.Context, owner, repo string, jobID int64) (*github.WorkflowJob, *github.Response, error)
	// ListRunners lists all runners within a repository.
	ListRunners(ctx context.Context, owner, repo string, opts *github.ListOptions) (*github.Runners, *github.Response, error)
	// ListRunnerApplicationDownloads returns a list of github runner application downloads for the
	// various supported operating systems and architectures.
	ListRunnerApplicationDownloads(ctx context.Context, owner, repo string) ([]*github.RunnerApplicationDownload, *github.Response, error)
	// RemoveRunner removes one runner from a repository.
	RemoveRunner(ctx context.Context, owner, repo string, runnerID int64) (*github.Response, error)
	// CreateRegistrationToken creates a runner registration token for one repository.
	CreateRegistrationToken(ctx context.Context, owner, repo string) (*github.RegistrationToken, *github.Response, error)
	// GenerateRepoJITConfig generates a just-in-time configuration for a repository.
	GenerateRepoJITConfig(ctx context.Context, owner, repo string, request *github.GenerateJITConfigRequest) (*github.JITRunnerConfig, *github.Response, error)

	// ListOrganizationRunners lists all runners within an organization.
	ListOrganizationRunners(ctx context.Context, owner string, opts *github.ListOptions) (*github.Runners, *github.Response, error)
	// ListOrganizationRunnerApplicationDownloads returns a list of github runner application downloads for the
	// various supported operating systems and architectures.
	ListOrganizationRunnerApplicationDownloads(ctx context.Context, owner string) ([]*github.RunnerApplicationDownload, *github.Response, error)
	// RemoveOrganizationRunner removes one github runner from an organization.
	RemoveOrganizationRunner(ctx context.Context, owner string, runnerID int64) (*github.Response, error)
	// CreateOrganizationRegistrationToken creates a runner registration token for an organization.
	CreateOrganizationRegistrationToken(ctx context.Context, owner string) (*github.RegistrationToken, *github.Response, error)
	// GenerateOrgJITConfig generate a just-in-time configuration for an organization.
	GenerateOrgJITConfig(ctx context.Context, owner string, request *github.GenerateJITConfigRequest) (*github.JITRunnerConfig, *github.Response, error)
	// ListOrganizationRunnerGroups lists all runner groups within an organization.
	ListOrganizationRunnerGroups(ctx context.Context, org string, opts *github.ListOrgRunnerGroupOptions) (*github.RunnerGroups, *github.Response, error)
}

GithubClient that describes the minimum list of functions we need to interact with github. Allows for easier testing.

type GithubEnterpriseClient

type GithubEnterpriseClient interface {
	// ListRunners lists all runners within a repository.
	ListRunners(ctx context.Context, enterprise string, opts *github.ListOptions) (*github.Runners, *github.Response, error)
	// RemoveRunner removes one runner from an enterprise.
	RemoveRunner(ctx context.Context, enterprise string, runnerID int64) (*github.Response, error)
	// CreateRegistrationToken creates a runner registration token for an enterprise.
	CreateRegistrationToken(ctx context.Context, enterprise string) (*github.RegistrationToken, *github.Response, error)
	// ListRunnerApplicationDownloads returns a list of github runner application downloads for the
	// various supported operating systems and architectures.
	ListRunnerApplicationDownloads(ctx context.Context, enterprise string) ([]*github.RunnerApplicationDownload, *github.Response, error)
	// GenerateEnterpriseJITConfig generate a just-in-time configuration for an enterprise.
	GenerateEnterpriseJITConfig(ctx context.Context, enterprise string, request *github.GenerateJITConfigRequest) (*github.JITRunnerConfig, *github.Response, error)
	// ListRunnerGroups lists all self-hosted runner groups configured in an enterprise.
	ListRunnerGroups(ctx context.Context, enterprise string, opts *github.ListEnterpriseRunnerGroupOptions) (*github.EnterpriseRunnerGroups, *github.Response, error)
}

type OrganizationHooks

type OrganizationHooks interface {
	ListOrgHooks(ctx context.Context, org string, opts *github.ListOptions) ([]*github.Hook, *github.Response, error)
	GetOrgHook(ctx context.Context, org string, id int64) (*github.Hook, *github.Response, error)
	CreateOrgHook(ctx context.Context, org string, hook *github.Hook) (*github.Hook, *github.Response, error)
	DeleteOrgHook(ctx context.Context, org string, id int64) (*github.Response, error)
	PingOrgHook(ctx context.Context, org string, id int64) (*github.Response, error)
}

type PoolManager

type PoolManager interface {
	// ID returns the ID of the entity (repo, org, enterprise)
	ID() string
	// WebhookSecret returns the unencrypted webhook secret associated with the webhook installed
	// in GitHub for GARM. For GARM to receive webhook events for an entity, either the operator or
	// GARM will have to create a webhook in GitHub which points to the GARM API server. To authenticate
	// the webhook, a webhook secret is used. This function returns that secret.
	WebhookSecret() string
	// GithubRunnerRegistrationToken returns a new registration token for a github runner. This is used
	// for GHES installations that have not yet upgraded to a version >= 3.10. Starting with 3.10, we use
	// just-in-time runners, which no longer require exposing a runner registration token.
	GithubRunnerRegistrationToken() (string, error)
	// HandleWorkflowJob handles a workflow job meant for a particular entity. When a webhook is fired for
	// a repo, org or enterprise, we determine the destination of that webhook, retrieve the pool manager
	// for it and call this function with the WorkflowJob as a parameter.
	HandleWorkflowJob(job params.WorkflowJob) error
	// RefreshState allows us to update webhook secrets and configuration for a pool manager.
	RefreshState(param params.UpdatePoolStateParams) error
	// ForceDeleteRunner will attempt to remove a runner from the pool.
	//
	// Deprecated: FunctionName is deprecated. Use DeleteRunner instead.
	ForceDeleteRunner(runner params.Instance) error

	// DeleteRunner will attempt to remove a runner from the pool. If forceRemove is true, any error
	// received from the provider will be ignored and we will procede to remove the runner from the database.
	// An error received while attempting to remove from GitHub (other than 404) will still stop the deletion
	// process. This can happen if the runner is already processing a job. At which point, you can simply cancel
	// the job in github. Doing so will prompt GARM to reap the runner automatically.
	DeleteRunner(runner params.Instance, forceRemove bool) error

	// InstallWebhook will create a webhook in github for the entity associated with this pool manager.
	InstallWebhook(ctx context.Context, param params.InstallWebhookParams) (params.HookInfo, error)
	// GetWebhookInfo will return information about the webhook installed in github for the entity associated
	GetWebhookInfo(ctx context.Context) (params.HookInfo, error)
	// UninstallWebhook will remove the webhook installed in github for the entity associated with this pool manager.
	UninstallWebhook(ctx context.Context) error

	// RootCABundle will return a CA bundle that must be installed on all runners in order to properly validate
	// x509 certificates used by various systems involved. This CA bundle is defined in the GARM config file and
	// can include multiple CA certificates for the GARM api server, GHES server and any provider API endpoint that
	// may use internal or self signed certificates.
	RootCABundle() (params.CertificateBundle, error)

	// Start will start the pool manager and all associated workers.
	Start() error
	// Stop will stop the pool manager and all associated workers.
	Stop() error
	// Status will return the current status of the pool manager.
	Status() params.PoolManagerStatus
	// Wait will block until the pool manager has stopped.
	Wait() error
}

type Provider

type Provider interface {
	// CreateInstance creates a new compute instance in the provider.
	CreateInstance(ctx context.Context, bootstrapParams commonParams.BootstrapInstance) (commonParams.ProviderInstance, error)
	// Delete instance will delete the instance in a provider.
	DeleteInstance(ctx context.Context, instance string) error
	// GetInstance will return details about one instance.
	GetInstance(ctx context.Context, instance string) (commonParams.ProviderInstance, error)
	// ListInstances will list all instances for a provider.
	ListInstances(ctx context.Context, poolID string) ([]commonParams.ProviderInstance, error)
	// RemoveAllInstances will remove all instances created by this provider.
	RemoveAllInstances(ctx context.Context) error
	// Stop shuts down the instance.
	Stop(ctx context.Context, instance string, force bool) error
	// Start boots up an instance.
	Start(ctx context.Context, instance string) error
	// DisableJITConfig tells us if the provider explicitly disables JIT configuration and
	// forces runner registration tokens to be used. This may happen if a provider has not yet
	// been updated to support JIT configuration.
	DisableJITConfig() bool

	AsParams() params.Provider
}

type RepositoryHooks

type RepositoryHooks interface {
	ListRepoHooks(ctx context.Context, owner, repo string, opts *github.ListOptions) ([]*github.Hook, *github.Response, error)
	GetRepoHook(ctx context.Context, owner, repo string, id int64) (*github.Hook, *github.Response, error)
	CreateRepoHook(ctx context.Context, owner, repo string, hook *github.Hook) (*github.Hook, *github.Response, error)
	DeleteRepoHook(ctx context.Context, owner, repo string, id int64) (*github.Response, error)
	PingRepoHook(ctx context.Context, owner, repo string, id int64) (*github.Response, error)
}