github

package
v0.27.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 29, 2025 License: Apache-2.0 Imports: 36 Imported by: 0

Documentation

Overview

Package github provides the ability for Vela to integrate with GitHub or GitHub Enterprise as a scm provider.

Usage: 

import "github.com/go-vela/server/scm/github"

Index

Constants

View Source 
const (
	// GitHub App install permission 'none'.
	AppInstallPermissionNone = "none"
	// GitHub App install permission 'read'.
	AppInstallPermissionRead = "read"
	// GitHub App install permission 'write'.
	AppInstallPermissionWrite = "write"
)

see: https://docs.github.com/en/rest/authentication/permissions-required-for-github-apps?apiVersion=2022-11-28

View Source 
const (
	// GitHub App install contents resource.
	AppInstallResourceContents = "contents"
	// GitHub App install checks resource.
	AppInstallResourceChecks = "checks"
	// GitHub App install packages resource.
	AppInstallResourcePackages = "packages"
)

Variables

This section is empty.

Functions

func ApplyInstallationPermissions added in v0.26.0 

func ApplyInstallationPermissions(resource, perm string, perms *github.InstallationPermissions) (*github.InstallationPermissions, error)

ApplyInstallationPermissions takes permissions and applies a new permission if valid.

func GetInstallationPermission added in v0.26.0 

func GetInstallationPermission(resource string, appPermissions *github.InstallationPermissions) (string, error)

GetInstallationPermission takes permissions and returns the permission level if valid.

func GetReadWriter added in v0.26.0 

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

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

func InstallationHasPermission added in v0.26.0 

func InstallationHasPermission(resource, requiredPerm, actualPerm string) error

InstallationHasPermission takes a resource:perm pair and checks if the actual permission matches the expected permission or is supersceded by a higher permission.

Types

type AppsTransport added in v0.26.0 

type AppsTransport struct {
	BaseURL string     // BaseURL is the scheme and host for GitHub API, defaults to https://api.github.com
	Client  HTTPClient // 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 NewTestAppsTransport added in v0.26.0 

func NewTestAppsTransport(baseURL string) *AppsTransport

NewTestAppsTransport creates a new AppsTransport for testing purposes.

func (*AppsTransport) RoundTrip added in v0.26.0 

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

RoundTrip implements http.RoundTripper interface.

type AppsTransportOption added in v0.26.0 

type AppsTransportOption func(*AppsTransport)

AppsTransportOption is a func option for configuring an AppsTransport.

func WithSigner added in v0.26.0 

func WithSigner(signer Signer) AppsTransportOption

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

type Client added in v0.26.0 

type Client struct {
	OAuth         *oauth2.Config
	AuthReq       *github.AuthorizationRequest
	Tracing       *tracing.Client
	AppsTransport *AppsTransport

	settings.SCM

	// https://pkg.go.dev/github.com/sirupsen/logrus#Entry
	Logger *logrus.Entry
	// contains filtered or unexported fields
}

func New 

func New(ctx context.Context, opts ...ClientOpt) (*Client, error)

New returns a SCM implementation that integrates with a GitHub or a GitHub Enterprise instance.

func NewTest 

func NewTest(urls ...string) (*Client, error)

NewTest returns a SCM implementation that integrates with the provided mock server. Only the url from the mock server is required.

This function is intended for running tests only.

func (*Client) Authenticate added in v0.27.0 

func (c *Client) Authenticate(ctx context.Context, _ http.ResponseWriter, r *http.Request, oAuthState string) (*api.User, error)

Authenticate completes the authentication workflow for the session and returns the remote user details.

func (*Client) AuthenticateToken added in v0.27.0 

func (c *Client) AuthenticateToken(ctx context.Context, r *http.Request) (*api.User, error)

AuthenticateToken completes the authentication workflow for the session and returns the remote user details.

func (*Client) Authorize added in v0.27.0 

func (c *Client) Authorize(ctx context.Context, token string) (string, error)

Authorize uses the given access token to authorize the user.

func (*Client) Changeset added in v0.27.0 

func (c *Client) Changeset(ctx context.Context, r *api.Repo, sha string) ([]string, error)

Changeset captures the list of files changed for a commit.

func (*Client) ChangesetPR added in v0.27.0 

func (c *Client) ChangesetPR(ctx context.Context, r *api.Repo, number int) ([]string, error)

ChangesetPR captures the list of files changed for a pull request.

func (*Client) Config added in v0.27.0 

func (c *Client) Config(ctx context.Context, u *api.User, r *api.Repo, ref string) ([]byte, error)

Config gets the pipeline configuration from the GitHub repo.

func (*Client) ConfigBackoff added in v0.27.0 

func (c *Client) ConfigBackoff(ctx context.Context, u *api.User, r *api.Repo, ref string) (data []byte, err error)

ConfigBackoff is a wrapper for Config that will retry five times if the function fails to retrieve the yaml/yml file.

func (*Client) CreateDeployment added in v0.27.0 

func (c *Client) CreateDeployment(ctx context.Context, u *api.User, r *api.Repo, d *api.Deployment) error

CreateDeployment creates a new deployment for the GitHub repo.

func (*Client) CreateWebhook added in v0.27.0 

func (c *Client) CreateWebhook(ctx context.Context, u *api.User, r *api.Repo, h *api.Hook) (*api.Hook, string, error)

CreateWebhook creates a repo's webhook.

func (*Client) DestroyWebhook added in v0.27.0 

func (c *Client) DestroyWebhook(ctx context.Context, u *api.User, org, name string) error

DestroyWebhook deletes a repo's webhook.

func (*Client) Disable added in v0.27.0 

func (c *Client) Disable(ctx context.Context, u *api.User, org, name string) error

Disable deactivates a repo by deleting the webhook.

func (*Client) Driver added in v0.27.0 

func (c *Client) Driver() string

Driver outputs the configured scm driver.

func (*Client) Enable added in v0.27.0 

func (c *Client) Enable(ctx context.Context, u *api.User, r *api.Repo, h *api.Hook) (*api.Hook, string, error)

Enable activates a repo by creating the webhook.

func (*Client) FinishInstallation added in v0.27.0 

func (c *Client) FinishInstallation(ctx context.Context, _ *http.Request, installID int64) (string, error)

FinishInstallation completes the web flow for a GitHub App installation, returning a redirect to the app installation page.

func (*Client) GetBranch added in v0.27.0 

func (c *Client) GetBranch(ctx context.Context, r *api.Repo, branch string) (string, string, error)

GetBranch defines a function that retrieves a branch for a repo.

func (*Client) GetDeployment added in v0.27.0 

func (c *Client) GetDeployment(ctx context.Context, u *api.User, r *api.Repo, id int64) (*api.Deployment, error)

GetDeployment gets a deployment from the GitHub repo.

func (*Client) GetDeploymentCount added in v0.27.0 

func (c *Client) GetDeploymentCount(ctx context.Context, u *api.User, r *api.Repo) (int64, error)

GetDeploymentCount counts a list of deployments from the GitHub repo.

func (*Client) GetDeploymentList added in v0.27.0 

func (c *Client) GetDeploymentList(ctx context.Context, u *api.User, r *api.Repo, page, perPage int) ([]*api.Deployment, error)

GetDeploymentList gets a list of deployments from the GitHub repo.

func (*Client) GetHTMLURL added in v0.27.0 

func (c *Client) GetHTMLURL(ctx context.Context, u *api.User, org, repo, name, ref string) (string, error)

GetHTMLURL retrieves the html_url from repository contents from the GitHub repo.

func (*Client) GetNetrcPassword added in v0.27.0 

func (c *Client) GetNetrcPassword(ctx context.Context, db database.Interface, r *api.Repo, u *api.User, g yaml.Git) (string, error)

GetNetrcPassword returns a clone token using the repo's github app installation if it exists. If not, it defaults to the user OAuth token.

func (*Client) GetOrgAndRepoName added in v0.27.0 

func (c *Client) GetOrgAndRepoName(ctx context.Context, u *api.User, o string, r string) (string, string, error)

GetOrgAndRepoName returns the name of the org and the repository in the SCM.

func (*Client) GetOrgName added in v0.27.0 

func (c *Client) GetOrgName(ctx context.Context, u *api.User, o string) (string, error)

GetOrgName gets org name from Github.

func (*Client) GetPullRequest added in v0.27.0 

func (c *Client) GetPullRequest(ctx context.Context, r *api.Repo, number int) (string, string, string, string, error)

GetPullRequest defines a function that retrieves a pull request for a repo.

func (*Client) GetRepo added in v0.27.0 

func (c *Client) GetRepo(ctx context.Context, u *api.User, r *api.Repo) (*api.Repo, int, error)

GetRepo gets repo information from Github.

func (*Client) GetSettings added in v0.27.0 

func (c *Client) GetSettings() settings.SCM

GetSettings retrieves the api settings type in the Engine.

func (*Client) GetUserID added in v0.27.0 

func (c *Client) GetUserID(ctx context.Context, name string, token string) (string, error)

GetUserID captures the user's scm id.

func (*Client) ListUserRepos added in v0.27.0 

func (c *Client) ListUserRepos(ctx context.Context, u *api.User) ([]string, error)

ListUserRepos returns a list of all repos the user has access to.

func (*Client) ListUsersTeamsForOrg added in v0.27.0 

func (c *Client) ListUsersTeamsForOrg(ctx context.Context, u *api.User, org string) ([]string, error)

ListUsersTeamsForOrg captures the user's teams for an org.

func (*Client) Login added in v0.27.0 

func (c *Client) Login(_ context.Context, w http.ResponseWriter, r *http.Request) (string, error)

Login begins the authentication workflow for the session.

func (*Client) OrgAccess added in v0.27.0 

func (c *Client) OrgAccess(ctx context.Context, u *api.User, org string) (string, error)

OrgAccess captures the user's access level for an org.

func (*Client) ProcessInstallation added in v0.27.0 

func (c *Client) ProcessInstallation(ctx context.Context, _ *http.Request, webhook *internal.Webhook, db database.Interface) error

ProcessInstallation takes a GitHub installation and processes the changes.

func (*Client) ProcessWebhook added in v0.27.0 

func (c *Client) ProcessWebhook(ctx context.Context, request *http.Request) (*internal.Webhook, error)

ProcessWebhook parses the webhook from a repo.

func (*Client) RedeliverWebhook added in v0.27.0 

func (c *Client) RedeliverWebhook(ctx context.Context, u *api.User, h *api.Hook) error

RedeliverWebhook redelivers webhooks from GitHub.

func (*Client) RepoAccess added in v0.27.0 

func (c *Client) RepoAccess(ctx context.Context, name, token, org, repo string) (string, error)

RepoAccess captures the user's access level for a repo.

func (*Client) RepoContributor added in v0.27.0 

func (c *Client) RepoContributor(ctx context.Context, owner *api.User, sender, org, repo string) (bool, error)

RepoContributor lists all contributors from a repository and checks if the sender is one of the contributors.

func (*Client) SetSettings added in v0.27.0 

func (c *Client) SetSettings(s *settings.Platform)

SetSettings sets the api settings type in the Engine.

func (*Client) Status added in v0.27.0 

func (c *Client) Status(ctx context.Context, b *api.Build, org, name, token string) error

Status sends the commit status for the given SHA from the GitHub repo.

func (*Client) StepStatus added in v0.27.0 

func (c *Client) StepStatus(ctx context.Context, b *api.Build, s *api.Step, org, name, token string) error

StepStatus sends the commit status for the given SHA to the GitHub repo with the step as the context.

func (*Client) SyncRepoWithInstallation added in v0.27.0 

func (c *Client) SyncRepoWithInstallation(ctx context.Context, r *api.Repo) (*api.Repo, error)

SyncRepoWithInstallation ensures the repo is synchronized with the scm installation, if it exists.

func (*Client) TeamAccess added in v0.27.0 

func (c *Client) TeamAccess(ctx context.Context, u *api.User, org, team string) (string, error)

TeamAccess captures the user's access level for a team.

func (*Client) Update added in v0.27.0 

func (c *Client) Update(ctx context.Context, u *api.User, r *api.Repo, hookID int64) (bool, error)

Update edits a repo webhook.

func (*Client) ValidateGitHubApp added in v0.27.0 

func (c *Client) ValidateGitHubApp(ctx context.Context) error

ValidateGitHubApp ensures the GitHub App configuration is valid.

func (*Client) ValidateOAuthToken added in v0.27.0 

func (c *Client) ValidateOAuthToken(ctx context.Context, token string) (bool, error)

ValidateOAuthToken takes a user oauth integration token and validates that it was created by the Vela OAuth app. In essence, the function expects either a 200 or 404 from the GitHub API and returns error in any other failure case.

func (*Client) VerifyWebhook added in v0.27.0 

func (c *Client) VerifyWebhook(_ context.Context, request *http.Request, secret []byte) error

VerifyWebhook verifies the webhook from a repo.

type ClientOpt 

type ClientOpt func(*Client) error

ClientOpt represents a configuration option to initialize the scm client for GitHub.

func WithAddress 

func WithAddress(address string) ClientOpt

WithAddress sets the GitHub address in the scm client for GitHub.

func WithClientID 

func WithClientID(id string) ClientOpt

WithClientID sets the OAuth client ID in the scm client for GitHub.

func WithClientSecret 

func WithClientSecret(secret string) ClientOpt

WithClientSecret sets the OAuth client secret in the scm client for GitHub.

func WithGitHubAppPermissions added in v0.26.0 

func WithGitHubAppPermissions(permissions []string) ClientOpt

WithGitHubAppPermissions sets the App permissions in the scm client for GitHub.

func WithGithubAppID added in v0.26.0 

func WithGithubAppID(id int64) ClientOpt

WithGithubAppID sets the ID for the GitHub App in the scm client.

func WithGithubPrivateKey added in v0.26.0 

func WithGithubPrivateKey(key string) ClientOpt

WithGithubPrivateKey sets the private key for the GitHub App in the scm client.

func WithGithubPrivateKeyPath added in v0.26.0 

func WithGithubPrivateKeyPath(path string) ClientOpt

WithGithubPrivateKeyPath sets the private key path for the GitHub App in the scm client.

func WithOAuthScopes added in v0.26.0 

func WithOAuthScopes(scopes []string) ClientOpt

WithOAuthScopes sets the OAuth scopes in the scm client for GitHub.

func WithOrgRoleMap added in v0.27.0 

func WithOrgRoleMap(mapping map[string]string) ClientOpt

WithOrgRoleMap sets the organization role mapping in the scm client for GitHub.

func WithRepoRoleMap added in v0.27.0 

func WithRepoRoleMap(mapping map[string]string) ClientOpt

WithRepoRoleMap sets the repository role mapping in the scm client for GitHub.

func WithServerAddress 

func WithServerAddress(address string) ClientOpt

WithServerAddress sets the Vela server address in the scm client for GitHub.

func WithServerWebhookAddress 

func WithServerWebhookAddress(address string) ClientOpt

WithServerWebhookAddress sets the Vela server webhook address in the scm client for GitHub.

func WithStatusContext 

func WithStatusContext(context string) ClientOpt

WithStatusContext sets the context for commit statuses in the scm client for GitHub.

func WithTeamRoleMap added in v0.27.0 

func WithTeamRoleMap(mapping map[string]string) ClientOpt

WithTeamRoleMap sets the team role mapping in the scm client for GitHub.

func WithTracing added in v0.25.0 

func WithTracing(tracing *tracing.Client) ClientOpt

WithTracing sets the shared tracing config in the scm client for GitHub.

func WithWebUIAddress 

func WithWebUIAddress(address string) ClientOpt

WithWebUIAddress sets the Vela web UI address in the scm client for GitHub.

type HTTPClient added in v0.27.0 

type HTTPClient interface {
	Do(*http.Request) (*http.Response, error)
}

HTTPClient is a HTTP client which sends a http.Request and returns a http.Response or an error.

type RSASigner added in v0.26.0 

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

RSASigner signs JWT tokens using RSA keys.

func NewRSASigner added in v0.26.0 

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

NewRSASigner creates a new RSASigner with the given RSA key.

func (*RSASigner) Sign added in v0.26.0 

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

Sign signs the JWT claims with the RSA key.

type Signer added in v0.26.0 

type Signer interface {
	// sign 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 added in v0.26.0 

type Transport struct {
	BaseURL string     // BaseURL is the scheme and host for GitHub API, defaults to https://api.github.com
	Client  HTTPClient // 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 (*Transport) Expiry added in v0.26.0 

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) RoundTrip added in v0.26.0 

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

RoundTrip implements http.RoundTripper interface.

func (*Transport) Token added in v0.26.0 

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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.