vcs

Documentation

Overview

Package vcs handles version control system stuff.

Index

• func NewTestModuleRepo(provider, name string) string
• func NewTestRepo() string
• type Action
• type Broker
  • func (b *Broker) Publish(event Event)
  • func (b *Broker) Subscribe(cb Callback)
• type Callback
• type Client
• type Commit
• type CommitAuthor
• type CreateWebhookOptions
• type DeleteWebhookOptions
• type ErrIgnoreEvent
  • func NewErrIgnoreEvent(msg string, args ...any) ErrIgnoreEvent
  • func (e ErrIgnoreEvent) Error() string
• type Event
• type EventHeader
• type EventPayload
  • func (e EventPayload) Validate() error
• type EventType
• type GetRepoTarballOptions
• type GetWebhookOptions
• type Kind
  • func KindPtr(k Kind) *Kind
• type ListRepositoriesOptions
• type ListTagsOptions
• type NewTokenClientOptions
• type Publisher
• type Repository
• type SetStatusOptions
• type Status
• type Subscriber
• type UpdateWebhookOptions
• type Webhook

Functions

func NewTestModuleRepo

func NewTestModuleRepo(provider, name string) string

func NewTestRepo

func NewTestRepo() string

Types

type Action

type Action string

const (
	ActionCreated Action = "created"
	ActionDeleted Action = "deleted"
	ActionMerged  Action = "merged"
	ActionUpdated Action = "updated"
)

type Broker

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

Broker is a brokerage for publishers and subscribers of VCS events.

func (*Broker) Publish

func (b *Broker) Publish(event Event)

func (*Broker) Subscribe

func (b *Broker) Subscribe(cb Callback)

type Callback

type Callback func(event Event)

type Client

type Client interface {
	// ListRepositories lists repositories accessible to the current user.
	ListRepositories(ctx context.Context, opts ListRepositoriesOptions) ([]string, error)
	GetRepository(ctx context.Context, identifier string) (Repository, error)
	// GetRepoTarball retrieves a .tar.gz tarball of a git repository
	GetRepoTarball(ctx context.Context, opts GetRepoTarballOptions) ([]byte, string, error)
	// CreateWebhook creates a webhook on the cloud provider, returning the
	// provider's unique ID for the webhook.
	CreateWebhook(ctx context.Context, opts CreateWebhookOptions) (string, error)
	UpdateWebhook(ctx context.Context, id string, opts UpdateWebhookOptions) error
	GetWebhook(ctx context.Context, opts GetWebhookOptions) (Webhook, error)
	DeleteWebhook(ctx context.Context, opts DeleteWebhookOptions) error
	SetStatus(ctx context.Context, opts SetStatusOptions) error
	// ListTags lists git tags on a repository. Each tag should be prefixed with
	// 'tags/'.
	ListTags(ctx context.Context, opts ListTagsOptions) ([]string, error)
	// ListPullRequestFiles returns the paths of files that are modified in the pull request
	ListPullRequestFiles(ctx context.Context, repo string, pull int) ([]string, error)
	// GetCommit retrieves commit from the repo with the given git ref
	GetCommit(ctx context.Context, repo, ref string) (Commit, error)
}

type Commit

type Commit struct {
	SHA    string
	URL    string
	Author CommitAuthor
}

type CommitAuthor

type CommitAuthor struct {
	Username   string
	ProfileURL string
	AvatarURL  string
}

type CreateWebhookOptions

type CreateWebhookOptions struct {
	Repo     string // repo identifier, <owner>/<repo>
	Secret   string // secret string for generating signature
	Endpoint string // otf's external-facing host[:port]
	Events   []EventType
}

type DeleteWebhookOptions

type DeleteWebhookOptions struct {
	Repo string // Repository identifier, <owner>/<repo>
	ID   string // vcs' webhook ID
}

DeleteWebhookOptions are options for deleting a webhook.

type ErrIgnoreEvent

type ErrIgnoreEvent struct {
	Reason string
}

ErrIgnoreEvent informs an upstream vcs provider why an event it sent is ignored.

func NewErrIgnoreEvent

func NewErrIgnoreEvent(msg string, args ...any) ErrIgnoreEvent

func (ErrIgnoreEvent) Error

func (e ErrIgnoreEvent) Error() string

type Event

type Event struct {
	EventHeader
	EventPayload
}

Event is a VCS event received from a cloud, e.g. a commit event from github

type EventHeader

type EventHeader struct {
	VCSProviderID string
}

type EventPayload

type EventPayload struct {
	RepoPath string

	VCSKind Kind

	Type          EventType
	Action        Action
	Tag           string
	CommitSHA     string
	CommitURL     string
	Branch        string // head branch
	DefaultBranch string

	PullRequestNumber int
	PullRequestURL    string
	PullRequestTitle  string

	SenderUsername  string
	SenderAvatarURL string
	SenderHTMLURL   string

	// Paths of files that have been added/modified/removed. Only applicable
	// to Push and Tag events types.
	Paths []string

	// Only set if event is from a github app
	GithubAppInstallID *int64
}

func (EventPayload) Validate

func (e EventPayload) Validate() error

type EventType

type EventType string

const (
	EventTypePull         EventType = "pull"
	EventTypePush         EventType = "push"
	EventTypeTag          EventType = "tag"
	EventTypeInstallation EventType = "install" // github-app installation
)

type GetRepoTarballOptions

type GetRepoTarballOptions struct {
	Repo string  // repo identifier, <owner>/<repo>
	Ref  *string // branch/tag/SHA ref, nil means default branch
}

type GetWebhookOptions

type GetWebhookOptions struct {
	Repo string // Repository identifier, <owner>/<repo>
	ID   string // vcs' webhook ID
}

GetWebhookOptions are options for retrieving a webhook.

type Kind

type Kind string

Kind of vcs hosting provider

const (
	GithubKind Kind = "github"
	GitlabKind Kind = "gitlab"
)

func KindPtr

func KindPtr(k Kind) *Kind

type ListRepositoriesOptions

type ListRepositoriesOptions struct {
	PageSize int
}

type ListTagsOptions

type ListTagsOptions struct {
	Repo   string // repo identifier, <owner>/<repo>
	Prefix string // only list tags that start with this string
}

ListTagsOptions are options for listing tags on a vcs repository

type NewTokenClientOptions

type NewTokenClientOptions struct {
	Token               string
	Hostname            string
	SkipTLSVerification bool
}

NewTokenClientOptions are options for creating a client using a personal access token (PAT).

type Publisher

type Publisher interface {
	Publish(Event)
}

type Repository

type Repository struct {
	Path          string
	DefaultBranch string
}

type SetStatusOptions

type SetStatusOptions struct {
	Workspace   string // workspace name
	Repo        string // <owner>/<repo>
	Ref         string // git ref
	Status      Status
	TargetURL   string
	Description string
}

SetStatusOptions are options for setting a status on a VCS repo

type Status

type Status string

const (
	PendingStatus Status = "pending"
	RunningStatus Status = "running"
	SuccessStatus Status = "success"
	ErrorStatus   Status = "error"
	FailureStatus Status = "failure"
)

type Subscriber

type Subscriber interface {
	Subscribe(cb Callback)
}

type UpdateWebhookOptions

type UpdateWebhookOptions CreateWebhookOptions

type Webhook

type Webhook struct {
	ID       string // cloud's webhook ID
	Repo     string // identifier is <repo_owner>/<repo_name>
	Events   []EventType
	Endpoint string // the OTF URL that receives events
}

Webhook is a cloud's configuration for a webhook.