source

Documentation

Overview

Package source provides the ability for Vela to integrate with different supported Source control providers.

Usage:

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

Index

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

Variables

var Flags = []cli.Flag{

	&cli.StringFlag{
		EnvVars:  []string{"VELA_SOURCE_LOG_FORMAT", "SOURCE_LOG_FORMAT", "VELA_LOG_FORMAT"},
		FilePath: "/vela/source/log_format",
		Name:     "source.log.format",
		Usage:    "format of logs to output",
		Value:    "json",
	},
	&cli.StringFlag{
		EnvVars:  []string{"VELA_SOURCE_LOG_LEVEL", "SOURCE_LOG_LEVEL", "VELA_LOG_LEVEL"},
		FilePath: "/vela/source/log_level",
		Name:     "source.log.level",
		Usage:    "level of logs to output",
		Value:    "info",
	},

	&cli.StringFlag{
		EnvVars:  []string{"VELA_SOURCE_DRIVER", "SOURCE_DRIVER"},
		FilePath: "/vela/source/driver",
		Name:     "source.driver",
		Usage:    "driver to be used for the version control system",
		Value:    constants.DriverGithub,
	},
	&cli.StringFlag{
		EnvVars:  []string{"VELA_SOURCE_ADDR", "SOURCE_ADDR"},
		FilePath: "/vela/source/addr",
		Name:     "source.addr",
		Usage:    "fully qualified url (<scheme>://<host>) for the version control system",
		Value:    "https://github.com",
	},
	&cli.StringFlag{
		EnvVars:  []string{"VELA_SOURCE_CLIENT", "SOURCE_CLIENT"},
		FilePath: "/vela/source/client",
		Name:     "source.client",
		Usage:    "OAuth client id from version control system",
	},
	&cli.StringFlag{
		EnvVars:  []string{"VELA_SOURCE_SECRET", "SOURCE_SECRET"},
		FilePath: "/vela/source/secret",
		Name:     "source.secret",
		Usage:    "OAuth client secret from version control system",
	},
	&cli.StringFlag{
		EnvVars:  []string{"VELA_SOURCE_CONTEXT", "SOURCE_CONTEXT"},
		FilePath: "/vela/source/context",
		Name:     "source.context",
		Usage:    "context for commit status in version control system",
		Value:    "continuous-integration/vela",
	},
	&cli.StringSliceFlag{
		EnvVars:  []string{"VELA_SOURCE_SCOPES", "SOURCE_SCOPES"},
		FilePath: "/vela/source/scopes",
		Name:     "source.scopes",
		Usage:    "OAuth scopes to be used for the version control system",
		Value:    cli.NewStringSlice("repo", "repo:status", "user:email", "read:user", "read:org"),
	},
	&cli.StringFlag{
		EnvVars:  []string{"VELA_SOURCE_WEBHOOK_ADDR", "SOURCE_WEBHOOK_ADDR"},
		FilePath: "/vela/source/webhook_addr",
		Name:     "source.webhook.addr",
		Usage: "Alternative or proxy server address as a fully qualified url (<scheme>://<host>). " +
			"Use this when the Vela server address that the source 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).",
	},
}

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

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

Functions

func ToContext

func ToContext(c Setter, s Service)

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

Types

type Service

type Service interface {

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

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

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

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

	// OrgAccess defines a function that captures
	// the user's access level for an org.
	OrgAccess(*library.User, string) (string, error)
	// RepoAccess defines a function that captures
	// the user's access level for a repo.
	RepoAccess(*library.User, string, string, string) (string, error)
	// TeamAccess defines a function that captures
	// the user's access level for a team.
	TeamAccess(*library.User, string, string) (string, error)

	// ListUsersTeamsForOrg defines a function that captures
	// the user's teams for an org
	ListUsersTeamsForOrg(*library.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(*library.User, *library.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(*library.User, *library.Repo, int) ([]string, error)

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

	// Config defines a function that captures
	// the pipeline configuration from a repo.
	Config(*library.User, *library.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(*library.User, *library.Repo, string) ([]byte, error)
	// Disable defines a function that deactivates
	// a repo by destroying the webhook.
	Disable(*library.User, string, string) error
	// Enable defines a function that activates
	// a repo by creating the webhook.
	Enable(*library.User, string, string, string) (string, error)
	// Status defines a function that sends the
	// commit status for the given SHA from a repo.
	Status(*library.User, *library.Build, string, string) error
	// ListUserRepos defines a function that retrieves
	// all repos with admin rights for the user.
	ListUserRepos(*library.User) ([]*library.Repo, error)
	// GetPullRequest defines a function that retrieves
	// a pull request for a repo.
	GetPullRequest(*library.User, *library.Repo, int) (string, string, string, string, error)
	// GetRepo defines a function that retrieves
	// details for a repo.
	GetRepo(*library.User, *library.Repo) (*library.Repo, error)
	// GetHTMLURL defines a function that retrieves
	// a repository file's html_url.
	GetHTMLURL(*library.User, string, string, string, string) (string, error)

	// ProcessWebhook defines a function that
	// parses the webhook from a repo.
	ProcessWebhook(*http.Request) (*types.Webhook, error)
	// VerifyWebhook defines a function that
	// verifies the webhook from a repo.
	VerifyWebhook(*http.Request, *library.Repo) error
}

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

func FromContext

func FromContext(c context.Context) Service

FromContext returns the source Service associated with this context.

func New

func New(s *Setup) (Service, error)

nolint: godot // top level comment ends in a list

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

Currently the following source 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 source client
	Driver string
	// specifies the address to use for the source client
	Address string
	// specifies the OAuth client ID from the source system to use for the source client
	ClientID string
	// specifies the OAuth client secret from the source system to use for the source client
	ClientSecret string
	// specifies the Vela server address to use for the source client
	ServerAddress string
	// specifies the Vela server address that the source provider should use to send Vela webhooks
	ServerWebhookAddress string
	// specifies the context for the commit status to use for the source client
	StatusContext string
	// specifies the Vela web UI address to use for the source client
	WebUIAddress string
	// specifies the OAuth scopes to use for the source client
	Scopes []string
}

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

func (*Setup) Github

func (s *Setup) Github() (Service, error)

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

func (*Setup) Gitlab

func (s *Setup) Gitlab() (Service, error)

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

func (*Setup) Validate

func (s *Setup) Validate() error

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