builder

README

Builders are the backbone of Conveyor. They're what takes a git commit, and turns it into a Docker image.

Builders

The following builder implementations are provided:

• Docker: This is a Builder implementation that builds Docker images inside Docker. It also tags the resulting image with the branch and git commit sha before pushing it to the docker registry.

Adding your own builder is easy. Just implement the following interface:

// Builder represents something that can build a Docker image.
type Builder interface {
	// Builder should build an image and write output to w.Writer. In general,
	// it's expected that the image will be pushed to some location where it
	// can be pulled by clients.
	//
	// Implementers should take note and handle the ctx.Done() case in the
	// event that the build should timeout or get canceled by the user.
	//
	// The value of image should be the location to pull the immutable
	// image. For example, if the image is built and generates a sha256
	// digest, the value for image may look like:
	//
	//	remind101/acme-inc@sha256:6b558cade79544da908c349ba0e5b63d
	//
	// Or possibly a tag:
	//
	//	remind101/acme-inc:<git sha>
	Build(ctx context.Context, w io.Writer, opts BuildOptions) (image string, err error)
}

Documentation

Overview

Package builder provides methods for building docker images from GitHub repositories.

Index

• Constants
• Variables
• func UpdateGitHubCommitStatus(b Builder, g GitHubClient, urlTmpl string) *statusUpdaterBuilder
• type BuildCanceledError
  • func (e *BuildCanceledError) Error() string
• type BuildOptions
• type Builder
  • func CloseWriter(b Builder) Builder
• type BuilderFunc
  • func (fn BuilderFunc) Build(ctx context.Context, w io.Writer, opts BuildOptions) (string, error)
• type CancelBuilder
  • func WithCancel(b Builder) *CancelBuilder
  • func (b *CancelBuilder) Build(ctx context.Context, w io.Writer, opts BuildOptions) (string, error)
  • func (b *CancelBuilder) Cancel() error
• type GitHubClient
  • func NewGitHubClient(token string) GitHubClient

Constants

const (
	// Context is used for the commit status context.
	Context = "container/docker"
)

Variables

var (
	// ErrShuttingDown can be returned by builders if they're shutting down
	// and not accepting more jobs.
	ErrShuttingDown = errors.New("shutting down")
)

Functions

func UpdateGitHubCommitStatus

func UpdateGitHubCommitStatus(b Builder, g GitHubClient, urlTmpl string) *statusUpdaterBuilder

UpdateGitHubCommitStatus wraps b to update the GitHub commit status when a build starts, and stops.

Types

type BuildCanceledError

type BuildCanceledError struct {
	Err    error
	Reason error
}

BuildCanceledError is returned if the build is canceled, or times out and the container returns an error.

func (*BuildCanceledError) Error

func (e *BuildCanceledError) Error() string

Error implements the error interface.

type BuildOptions

type BuildOptions struct {
	// A unique identifier for the build.
	ID string
	// Repository is the repo to build.
	Repository string
	// Sha is the git commit to build.
	Sha string
	// Branch is the name of the branch that this build relates to.
	Branch string
	// Set to true to disable the layer cache. The zero value is to enable
	// caching.
	NoCache bool
}

BuildOptions is provided when building an image.

type Builder

type Builder interface {
	// Builder should build an image and write output to w.Writer. In general,
	// it's expected that the image will be pushed to some location where it
	// can be pulled by clients.
	//
	// Implementers should take note and handle the ctx.Done() case in the
	// event that the build should timeout or get canceled by the user.
	//
	// The value of image should be the location to pull the immutable
	// image. For example, if the image is built and generates a sha256
	// digest, the value for image may look like:
	//
	//	remind101/acme-inc@sha256:6b558cade79544da908c349ba0e5b63d
	//
	// Or possibly a tag:
	//
	//	remind101/acme-inc:<git sha>
	Build(ctx context.Context, w io.Writer, opts BuildOptions) (image string, err error)
}

Builder represents something that can build a Docker image.

func CloseWriter

func CloseWriter(b Builder) Builder

CloseWriter wraps a Builder to call Close on w if it implements the io.Closer interface.

type BuilderFunc

type BuilderFunc func(context.Context, io.Writer, BuildOptions) (string, error)

BuilderFunc is a function that implements the Builder interface.

func (BuilderFunc) Build

func (fn BuilderFunc) Build(ctx context.Context, w io.Writer, opts BuildOptions) (string, error)

Build implements Builder Build.

type CancelBuilder

type CancelBuilder struct {
	Builder

	sync.Mutex
	// contains filtered or unexported fields
}

func WithCancel

func WithCancel(b Builder) *CancelBuilder

WithCancel wraps a Builder with a method to stop all builds.

func (*CancelBuilder) Build

func (b *CancelBuilder) Build(ctx context.Context, w io.Writer, opts BuildOptions) (string, error)

func (*CancelBuilder) Cancel

func (b *CancelBuilder) Cancel() error

type GitHubClient

type GitHubClient interface {
	CreateStatus(owner, repo, ref string, status *github.RepoStatus) (*github.RepoStatus, *github.Response, error)
}

GitHubClient represents a client that can create github commit statuses.

func NewGitHubClient

func NewGitHubClient(token string) GitHubClient

NewGitHubClient returns a new GitHubClient instance. If token is an empty string, then a fake client will be returned.