scm

Documentation

Overview

package scm provides the ability for Vela to integrate with different supported SCM providers.

Usage:

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

Index

• Variables
• func ToContext(c Setter, s Service)
• func WithGinContext(c *gin.Context, s Service)
• type Service
  • func FromContext(c context.Context) Service
  • func New(ctx context.Context, s *Setup) (Service, error)
• type Setter
• type Setup
  • func (s *Setup) Github(ctx context.Context) (Service, error)
  • func (s *Setup) Gitlab(_ context.Context) (Service, error)
  • func (s *Setup) Validate() error

Variables

var Flags = []cli.Flag{

	&cli.StringFlag{
		Name:  "scm.driver",
		Usage: "driver to be used for the version control system",
		Sources: cli.NewValueSourceChain(
			cli.EnvVar("VELA_SCM_DRIVER"),
			cli.EnvVar("SCM_DRIVER"),
			cli.File("/vela/scm/driver"),
		),
		Value: constants.DriverGithub,
	},
	&cli.StringFlag{
		Name:  "scm.addr",
		Usage: "fully qualified url (<scheme>://<host>) for the version control system",
		Sources: cli.NewValueSourceChain(
			cli.EnvVar("VELA_SCM_ADDR"),
			cli.EnvVar("SCM_ADDR"),
			cli.File("/vela/scm/addr"),
		),
		Value: "https://github.com",
		Action: func(_ context.Context, _ *cli.Command, v string) error {
			if !strings.Contains(v, "://") {
				return fmt.Errorf("scm address must be fully qualified (<scheme>://<host>)")
			}

			if strings.HasSuffix(v, "/") {
				return fmt.Errorf("scm address must not have trailing slash")
			}

			return nil
		},
	},
	&cli.StringFlag{
		Name:  "scm.client",
		Usage: "OAuth client id from version control system",
		Sources: cli.NewValueSourceChain(
			cli.EnvVar("VELA_SCM_CLIENT"),
			cli.EnvVar("SCM_CLIENT"),
			cli.File("/vela/scm/client"),
		),
		Required: true,
	},
	&cli.StringFlag{
		Name:  "scm.secret",
		Usage: "OAuth client secret from version control system",
		Sources: cli.NewValueSourceChain(
			cli.EnvVar("VELA_SCM_SECRET"),
			cli.EnvVar("SCM_SECRET"),
			cli.File("/vela/scm/secret"),
		),
		Required: true,
	},
	&cli.BoolFlag{
		Name:    "vela-disable-webhook-validation",
		Usage:   "determines whether or not webhook validation is disabled.  useful for local development.",
		Sources: cli.EnvVars("VELA_DISABLE_WEBHOOK_VALIDATION"),
		Value:   false,
	},
	&cli.StringFlag{
		Name:  "scm.context",
		Usage: "context for commit status in version control system",
		Sources: cli.NewValueSourceChain(
			cli.EnvVar("VELA_SCM_CONTEXT"),
			cli.EnvVar("SCM_CONTEXT"),
			cli.File("/vela/scm/context"),
		),
		Value: "continuous-integration/vela",
	},
	&cli.StringSliceFlag{
		Name:  "scm.scopes",
		Usage: "OAuth scopes to be used for the version control system",
		Sources: cli.NewValueSourceChain(
			cli.EnvVar("VELA_SCM_SCOPES"),
			cli.EnvVar("SCM_SCOPES"),
			cli.File("/vela/scm/scopes"),
		),
		Value: []string{"repo", "repo:status", "user:email", "read:user", "read:org"},
	},
	&cli.StringFlag{
		Name: "scm.webhook.addr",
		Usage: "Alternative or proxy server address as a fully qualified url (<scheme>://<host>). " +
			"Use this when the Vela server address that the scm provider can send webhooks to " +
			"differs from the server address the UI and oauth flows use, such as when the server " +
			"is behind a Firewall or NAT, or when using something like ngrok to forward webhooks. " +
			"(defaults to VELA_ADDR).",
		Sources: cli.NewValueSourceChain(
			cli.EnvVar("VELA_SCM_WEBHOOK_ADDR"),
			cli.EnvVar("SCM_WEBHOOK_ADDR"),
			cli.File("/vela/scm/webhook_addr"),
		),
	},
	&cli.Int64Flag{
		Name:  "scm.app.id",
		Usage: "set ID for the SCM App integration (GitHub App)",
		Sources: cli.NewValueSourceChain(
			cli.EnvVar("VELA_SCM_APP_ID"),
			cli.EnvVar("SCM_APP_ID"),
			cli.File("/vela/scm/app_id"),
		),
		Action: func(_ context.Context, cmd *cli.Command, v int64) error {
			if v > 0 {
				if !cmd.Bool("vela-disable-webhook-validation") && cmd.String("scm.app.webhook-secret") == "" {
					return fmt.Errorf("webhook-validation enabled and app ID provided but no app webhook secret is provided")
				}
				if cmd.String("scm.app.private-key") == "" && cmd.String("scm.app.private-key.path") == "" {
					return fmt.Errorf("app ID provided but no app private key is provided")
				}
				if cmd.String("scm.app.private-key") != "" && cmd.String("scm.app.private-key.path") != "" {
					return fmt.Errorf("app ID provided but both app private key and app private key path are provided")
				}
			}

			return nil
		},
	},
	&cli.StringFlag{
		Name:  "scm.app.private-key",
		Usage: "set value of base64 encoded SCM App integration (GitHub App) private key",
		Sources: cli.NewValueSourceChain(
			cli.EnvVar("VELA_SCM_APP_PRIVATE_KEY"),
			cli.EnvVar("SCM_APP_PRIVATE_KEY"),
			cli.File("/vela/scm/app_private_key"),
		),
	},
	&cli.StringFlag{
		Name:  "scm.app.private-key.path",
		Usage: "set filepath to the SCM App integration (GitHub App) private key",
		Sources: cli.NewValueSourceChain(
			cli.EnvVar("VELA_SCM_APP_PRIVATE_KEY_PATH"),
			cli.EnvVar("SCM_APP_PRIVATE_KEY_PATH"),
			cli.File("/vela/scm/app_private_key_path"),
		),
	},
	&cli.StringFlag{
		Name:  "scm.app.webhook-secret",
		Usage: "set value of SCM App integration webhook secret",
		Sources: cli.NewValueSourceChain(
			cli.EnvVar("VELA_SCM_APP_WEBHOOK_SECRET"),
			cli.EnvVar("SCM_APP_WEBHOOK_SECRET"),
			cli.File("/vela/scm/app_webhook_secret"),
		),
	},
	&cli.StringSliceFlag{
		Name:  "scm.app.permissions",
		Usage: "SCM App integration (GitHub App) permissions to be used as the allowed set of possible installation token permissions",
		Sources: cli.NewValueSourceChain(
			cli.EnvVar("VELA_SCM_APP_PERMISSIONS"),
			cli.EnvVar("SCM_APP_PERMISSIONS"),
			cli.File("/vela/scm/app/permissions"),
		),
		Value: []string{"contents:read", "checks:write"},
	},
	&cli.StringMapFlag{
		Name:  "scm.repo.roles-map",
		Usage: "map of SCM roles to Vela permissions for repositories",
		Sources: cli.NewValueSourceChain(
			cli.EnvVar("VELA_SCM_REPO_ROLES_MAP"),
			cli.EnvVar("SCM_REPO_ROLES_MAP"),
			cli.File("/vela/scm/repo/roles_map"),
		),
		Value: map[string]string{
			"admin":    constants.PermissionAdmin,
			"write":    constants.PermissionWrite,
			"maintain": constants.PermissionWrite,
			"triage":   constants.PermissionRead,
			"read":     constants.PermissionRead,
		},
		Action: func(_ context.Context, _ *cli.Command, v map[string]string) error {
			return util.ValidateRoleMap(v, "repo")
		},
	},
	&cli.StringMapFlag{
		Name:  "scm.org.roles-map",
		Usage: "map of SCM roles to Vela permissions for organizations",
		Sources: cli.NewValueSourceChain(
			cli.EnvVar("VELA_SCM_ORG_ROLES_MAP"),
			cli.EnvVar("SCM_ORG_ROLES_MAP"),
			cli.File("/vela/scm/org/roles_map"),
		),
		Value: map[string]string{
			"admin":  constants.PermissionAdmin,
			"member": constants.PermissionRead,
		},
		Action: func(_ context.Context, _ *cli.Command, v map[string]string) error {
			return util.ValidateRoleMap(v, "org")
		},
	},
	&cli.StringMapFlag{
		Name:  "scm.team.roles-map",
		Usage: "map of SCM roles to Vela permissions for teams",
		Sources: cli.NewValueSourceChain(
			cli.EnvVar("VELA_SCM_TEAM_ROLES_MAP"),
			cli.EnvVar("SCM_TEAM_ROLES_MAP"),
			cli.File("/vela/scm/team/roles_map"),
		),
		Value: map[string]string{
			"maintainer": constants.PermissionAdmin,
			"member":     constants.PermissionRead,
		},
		Action: func(_ context.Context, _ *cli.Command, v map[string]string) error {
			return util.ValidateRoleMap(v, "team")
		},
	},
}

Flags represents all supported command line interface (CLI) flags for the scm.

https://pkg.go.dev/github.com/urfave/cli?tab=doc#Flag

Functions

func ToContext

func ToContext(c Setter, s Service)

ToContext adds the scm Service to this context if it supports the Setter interface.

func WithGinContext

func WithGinContext(c *gin.Context, s Service)

WithGinContext inserts the scm Service into the gin.Context.

Types

type Service

type Service interface {

	// Driver defines a function that outputs
	// the configured scm driver.
	Driver() string

	// Authorize defines a function that uses the
	// given access token to authorize the user.
	Authorize(context.Context, string) (string, error)
	// Authenticate defines a function that completes
	// the OAuth workflow for the session.
	Authenticate(context.Context, http.ResponseWriter, *http.Request, string) (*api.User, error)

	// AuthenticateToken defines a function that completes
	// the OAuth workflow for the session using PAT Token
	AuthenticateToken(context.Context, *http.Request) (*api.User, error)

	// ValidateOAuthToken defines a function that validates
	// an OAuth access token was created by Vela
	ValidateOAuthToken(context.Context, string) (bool, error)

	// Login defines a function that begins
	// the OAuth workflow for the session.
	Login(context.Context, http.ResponseWriter, *http.Request) (string, error)

	// GetUserID defines a function that captures
	// the scm user id attached to the username.
	GetUserID(context.Context, string, string) (string, error)

	// OrgAccess defines a function that captures
	// the user's access level for an org.
	OrgAccess(context.Context, *api.User, string) (string, error)
	// RepoAccess defines a function that captures
	// the user's access level for a repo.
	RepoAccess(context.Context, string, string, string, string) (string, error)
	// TeamAccess defines a function that captures
	// the user's access level for a team.
	TeamAccess(context.Context, *api.User, string, string) (string, error)
	// RepoContributor defines a function that captures
	// whether the user is a contributor for a repo.
	RepoContributor(context.Context, *api.User, string, string, string) (bool, error)

	// ListUsersTeamsForOrg defines a function that captures
	// the user's teams for an org
	ListUsersTeamsForOrg(context.Context, *api.User, string) ([]string, error)

	// Changeset defines a function that captures the list
	// of files changed for a commit.
	//
	// https://en.wikipedia.org/wiki/Changeset.
	Changeset(context.Context, *api.Repo, string) ([]string, error)
	// ChangesetPR defines a function that captures the list
	// of files changed for a pull request.
	//
	// https://en.wikipedia.org/wiki/Changeset.
	ChangesetPR(context.Context, *api.Repo, int) ([]string, error)

	// GetDeployment defines a function that
	// gets a deployment by number and repo.
	GetDeployment(context.Context, *api.User, *api.Repo, int64) (*api.Deployment, error)
	// GetDeploymentCount defines a function that
	// counts a list of all deployment for a repo.
	GetDeploymentCount(context.Context, *api.User, *api.Repo) (int64, error)
	// GetDeploymentList defines a function that gets
	// a list of all deployments for a repo.
	GetDeploymentList(context.Context, *api.User, *api.Repo, int, int) ([]*api.Deployment, error)
	// CreateDeployment defines a function that
	// creates a new deployment.
	CreateDeployment(context.Context, *api.User, *api.Repo, *api.Deployment) error

	// Config defines a function that captures
	// the pipeline configuration from a repo.
	Config(context.Context, *api.User, *api.Repo, string) ([]byte, error)
	// ConfigBackoff is a truncated constant backoff wrapper for Config.
	// Retry again in five seconds if Config fails to retrieve yaml/yml file.
	// Will return an error after five failed attempts.
	ConfigBackoff(context.Context, *api.User, *api.Repo, string) ([]byte, error)
	// Disable defines a function that deactivates
	// a repo by destroying the webhook.
	Disable(context.Context, *api.User, string, string) error
	// Enable defines a function that activates
	// a repo by creating the webhook.
	Enable(context.Context, *api.User, *api.Repo, *api.Hook) (*api.Hook, string, error)
	// Update defines a function that updates
	// a webhook for a specified repo.
	Update(context.Context, *api.User, *api.Repo, int64) (bool, error)
	// Status defines a function that sends the
	// commit status for the given SHA from a repo.
	Status(context.Context, *api.Build, string, string, string) error
	// StepStatus defines a function that sends the
	// commit status for the given SHA for a specified step context.
	StepStatus(context.Context, *api.Build, *api.Step, string, string, string) error
	// ListUserRepos defines a function that retrieves
	// all repos with admin rights for the user.
	ListUserRepos(context.Context, *api.User) ([]string, error)
	// GetBranch defines a function that retrieves
	// a branch for a repo.
	GetBranch(context.Context, *api.Repo, string) (string, string, error)
	// GetPullRequest defines a function that retrieves
	// a pull request for a repo.
	GetPullRequest(context.Context, *api.Repo, int) (string, string, string, string, error)
	// GetRepo defines a function that retrieves
	// details for a repo.
	GetRepo(context.Context, *api.User, *api.Repo) (*api.Repo, int, error)
	// GetOrgAndRepoName defines a function that retrieves
	// the name of the org and repo in the SCM.
	GetOrgAndRepoName(context.Context, *api.User, string, string) (string, string, error)
	// GetOrg defines a function that retrieves
	// the name for an org in the SCM.
	GetOrgName(context.Context, *api.User, string) (string, error)
	// GetHTMLURL defines a function that retrieves
	// a repository file's html_url.
	GetHTMLURL(context.Context, *api.User, string, string, string, string) (string, error)
	// GetNetrcPassword defines a function that returns the netrc
	// password injected into build steps.
	GetNetrcPassword(context.Context, database.Interface, *api.Repo, *api.User, yaml.Git) (string, error)
	// SyncRepoWithInstallation defines a function that syncs
	// a repo with the installation, if it exists.
	SyncRepoWithInstallation(context.Context, *api.Repo) (*api.Repo, error)

	// ProcessWebhook defines a function that
	// parses the webhook from a repo.
	ProcessWebhook(context.Context, *http.Request) (*internal.Webhook, error)
	// VerifyWebhook defines a function that
	// verifies the webhook from a repo.
	VerifyWebhook(context.Context, *http.Request, []byte) error
	// RedeliverWebhook defines a function that
	// redelivers the webhook from the SCM.
	RedeliverWebhook(context.Context, *api.User, *api.Hook) error

	// ProcessInstallation defines a function that
	// processes an installation event.
	ProcessInstallation(context.Context, *http.Request, *internal.Webhook, database.Interface) error
	// FinishInstallation defines a function that
	// finishes an installation event and returns a web redirect.
	FinishInstallation(context.Context, *http.Request, int64) (string, error)

	// GetSettings defines a function that returns
	// scm settings.
	GetSettings() settings.SCM

	// SetSettings defines a function that takes api settings
	// and updates the compiler Engine.
	SetSettings(*settings.Platform)
}

Service represents the interface for Vela integrating with the different supported scm providers.

func FromContext

func FromContext(c context.Context) Service

FromContext returns the scm Service associated with this context.

func New

func New(ctx context.Context, s *Setup) (Service, error)

New creates and returns a Vela service capable of integrating with the configured scm provider.

Currently the following scm providers are supported:

* Github .

type Setter

type Setter interface {
	Set(string, interface{})
}

Setter defines a context that enables setting values.

type Setup

type Setup struct {

	// specifies the driver to use for the scm client
	Driver string
	// specifies the address to use for the scm client
	Address string
	// specifies the OAuth client ID from the scm system to use for the scm client
	ClientID string
	// specifies the OAuth client secret from the scm system to use for the scm client
	ClientSecret string
	// specifies App integration id
	AppID int64
	// specifies App integration private key
	AppPrivateKey string
	// specifies App integration path to private key
	AppPrivateKeyPath string
	// specifies App integration permissions set
	AppPermissions []string
	// specifies the Vela server address to use for the scm client
	ServerAddress string
	// specifies the Vela server address that the scm provider should use to send Vela webhooks
	ServerWebhookAddress string
	// specifies the context for the commit status to use for the scm client
	StatusContext string
	// specifies the Vela web UI address to use for the scm client
	WebUIAddress string
	// specifies the OAuth scopes to use for the scm client
	OAuthScopes []string
	// specifies the repo role map to use for the scm client
	RepoRoleMap map[string]string
	// specifies the org role map to use for the scm client
	OrgRoleMap map[string]string
	// specifies the team role map to use for the scm client
	TeamRoleMap map[string]string
	// specifies OTel tracing configurations
	Tracing *tracing.Client
}

Setup represents the configuration necessary for creating a Vela service capable of integrating with a configured scm system.

func (*Setup) Github

func (s *Setup) Github(ctx context.Context) (Service, error)

Github creates and returns a Vela service capable of integrating with a Github scm system.

func (*Setup) Gitlab

func (s *Setup) Gitlab(_ context.Context) (Service, error)

Gitlab creates and returns a Vela service capable of integrating with a Gitlab scm system.

func (*Setup) Validate

func (s *Setup) Validate() error

Validate verifies the necessary fields for the provided configuration are populated correctly.