github

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
• func ApplyInstallationPermissions(resource, perm string, perms *github.InstallationPermissions) (*github.InstallationPermissions, error)
• func GetInstallationPermission(resource string, appPermissions *github.InstallationPermissions) (string, error)
• func GetReadWriter(i interface{}) (io.ReadWriter, error)
• func InstallationHasPermission(resource, requiredPerm, actualPerm string) error
• func New(ctx context.Context, opts ...ClientOpt) (*client, error)
• func NewTest(urls ...string) (*client, error)
• type AppsTransport
  • func NewTestAppsTransport(baseURL string) *AppsTransport
  • func (t *AppsTransport) RoundTrip(req *http.Request) (*http.Response, error)
• type AppsTransportOption
  • func WithSigner(signer Signer) AppsTransportOption
• type Client
• type ClientOpt
  • func WithAddress(address string) ClientOpt
  • func WithClientID(id string) ClientOpt
  • func WithClientSecret(secret string) ClientOpt
  • func WithGitHubAppPermissions(permissions []string) ClientOpt
  • func WithGithubAppID(id int64) ClientOpt
  • func WithGithubPrivateKey(key string) ClientOpt
  • func WithGithubPrivateKeyPath(path string) ClientOpt
  • func WithOAuthScopes(scopes []string) ClientOpt
  • func WithServerAddress(address string) ClientOpt
  • func WithServerWebhookAddress(address string) ClientOpt
  • func WithStatusContext(context string) ClientOpt
  • func WithTracing(tracing *tracing.Client) ClientOpt
  • func WithWebUIAddress(address string) ClientOpt
• type RSASigner
  • func NewRSASigner(method *jwt.SigningMethodRSA, key *rsa.PrivateKey) *RSASigner
  • func (s *RSASigner) Sign(claims jwt.Claims) (string, error)
• type Signer
• type Transport
  • func (t *Transport) Expiry() (expiresAt time.Time, refreshAt time.Time, err error)
  • func (t *Transport) RoundTrip(req *http.Request) (*http.Response, error)
  • func (t *Transport) Token(ctx context.Context) (string, error)

Constants

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

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

Functions

func ApplyInstallationPermissions

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

ApplyInstallationPermissions takes permissions and applies a new permission if valid.

func GetInstallationPermission

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

GetInstallationPermission takes permissions and returns the permission level if valid.

func GetReadWriter

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

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

func InstallationHasPermission

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.

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.

Types

type AppsTransport

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

func NewTestAppsTransport(baseURL string) *AppsTransport

NewTestAppsTransport creates a new AppsTransport for testing purposes.

func (*AppsTransport) RoundTrip

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

RoundTrip implements http.RoundTripper interface.

type AppsTransportOption

type AppsTransportOption func(*AppsTransport)

AppsTransportOption is a func option for configuring an AppsTransport.

func WithSigner

func WithSigner(signer Signer) AppsTransportOption

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

type Client

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

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

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

func WithGitHubAppPermissions(permissions []string) ClientOpt

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

func WithGithubAppID

func WithGithubAppID(id int64) ClientOpt

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

func WithGithubPrivateKey

func WithGithubPrivateKey(key string) ClientOpt

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

func WithGithubPrivateKeyPath

func WithGithubPrivateKeyPath(path string) ClientOpt

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

func WithOAuthScopes

func WithOAuthScopes(scopes []string) ClientOpt

WithOAuthScopes sets the OAuth scopes 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 WithTracing

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 RSASigner

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

RSASigner signs JWT tokens using RSA keys.

func NewRSASigner

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

NewRSASigner creates a new RSASigner with the given RSA key.

func (*RSASigner) Sign

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

Sign signs the JWT claims with the RSA key.

type Signer

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

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

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

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

RoundTrip implements http.RoundTripper interface.

func (*Transport) Token

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.