bootstrap

Documentation

Overview

Package bootstrap provides management of the phases of execution of a Buildkite job.

It is intended for internal use by buildkite-agent only.

Index

• func DDTracingExtras() map[string]any
• func GenericTracingExtras(b *Bootstrap, env *env.Environment) map[string]any
• func Merge(maps ...map[string]any) map[string]any
• type Bootstrap
  • func New(conf Config) *Bootstrap
  • func (b *Bootstrap) Cancel() error
  • func (b *Bootstrap) CheckoutPhase(ctx context.Context) error
  • func (b *Bootstrap) CommandPhase(ctx context.Context) (error, error)
  • func (b *Bootstrap) PluginPhase(ctx context.Context) error
  • func (b *Bootstrap) Run(ctx context.Context) (exitCode int)
  • func (b *Bootstrap) VendoredPluginPhase(ctx context.Context) error
• type Config
  • func (c *Config) ReadFromEnvironment(environ *env.Environment) map[string]string
• type HookConfig

Functions

func DDTracingExtras

func DDTracingExtras() map[string]any

func GenericTracingExtras

func GenericTracingExtras(b *Bootstrap, env *env.Environment) map[string]any

func Merge

func Merge(maps ...map[string]any) map[string]any

Types

type Bootstrap

type Bootstrap struct {
	// Config provides the bootstrap configuration
	Config
	// contains filtered or unexported fields
}

Bootstrap represents the phases of execution in a Buildkite Job. It's run as a sub-process of the buildkite-agent and finishes at the conclusion of a job.

Historically (prior to v3) the bootstrap was a shell script, but was ported to Go for portability and testability.

func New

func New(conf Config) *Bootstrap

New returns a new Bootstrap instance

func (*Bootstrap) Cancel

func (b *Bootstrap) Cancel() error

Cancel interrupts any running shell processes and causes the bootstrap to stop

func (*Bootstrap) CheckoutPhase

func (b *Bootstrap) CheckoutPhase(ctx context.Context) error

CheckoutPhase creates the build directory and makes sure we're running the build at the right commit.

func (*Bootstrap) CommandPhase

func (b *Bootstrap) CommandPhase(ctx context.Context) (error, error)

CommandPhase determines how to run the build, and then runs it

func (*Bootstrap) PluginPhase

func (b *Bootstrap) PluginPhase(ctx context.Context) error

PluginPhase is where plugins that weren't filtered in the Environment phase are checked out and made available to later phases

func (*Bootstrap) Run

func (b *Bootstrap) Run(ctx context.Context) (exitCode int)

Run the bootstrap and return the exit code

func (*Bootstrap) VendoredPluginPhase

func (b *Bootstrap) VendoredPluginPhase(ctx context.Context) error

VendoredPluginPhase is where plugins that are included in the checked out code are added

type Config

type Config struct {
	// The command to run
	Command string

	// The ID of the job being run
	JobID string

	// If the bootstrap is in debug mode
	Debug bool

	// The repository that needs to be cloned
	Repository string `env:"BUILDKITE_REPO"`

	// The commit being built
	Commit string

	// The branch of the commit
	Branch string

	// The tag of the job commit
	Tag string

	// Optional refspec to override git fetch
	RefSpec string `env:"BUILDKITE_REFSPEC"`

	// Plugin definition for the job
	Plugins string

	// Should git submodules be checked out
	GitSubmodules bool

	// If the commit was part of a pull request, this will container the PR number
	PullRequest string

	// The provider of the pipeline
	PipelineProvider string

	// Slug of the current organization
	OrganizationSlug string

	// Slug of the current pipeline
	PipelineSlug string

	// Name of the agent running the bootstrap
	AgentName string

	// Name of the queue the agent belongs to, if tagged
	Queue string

	// Should the bootstrap remove an existing checkout before running the job
	CleanCheckout bool `env:"BUILDKITE_CLEAN_CHECKOUT"`

	// Flags to pass to "git checkout" command
	GitCheckoutFlags string `env:"BUILDKITE_GIT_CHECKOUT_FLAGS"`

	// Flags to pass to "git clone" command
	GitCloneFlags string `env:"BUILDKITE_GIT_CLONE_FLAGS"`

	// Flags to pass to "git fetch" command
	GitFetchFlags string `env:"BUILDKITE_GIT_FETCH_FLAGS"`

	// Flags to pass to "git clone" command for mirroring
	GitCloneMirrorFlags string `env:"BUILDKITE_GIT_CLONE_MIRROR_FLAGS"`

	// Flags to pass to "git clean" command
	GitCleanFlags string `env:"BUILDKITE_GIT_CLEAN_FLAGS"`

	// Config key=value pairs to pass to "git" when submodule init commands are invoked
	GitSubmoduleCloneConfig []string `env:"BUILDKITE_GIT_SUBMODULE_CLONE_CONFIG" normalize:"list"`

	// Whether or not to run the hooks/commands in a PTY
	RunInPty bool

	// Are arbitrary commands allowed to be executed
	CommandEval bool

	// Are plugins enabled?
	PluginsEnabled bool

	// Should we always force a fresh clone of plugins, even if we have a local checkout?
	PluginsAlwaysCloneFresh bool `env:"BUILDKITE_PLUGINS_ALWAYS_CLONE_FRESH"`

	// Whether to validate plugin configuration
	PluginValidation bool

	// Are local hooks enabled?
	LocalHooksEnabled bool

	// Path where the builds will be run
	BuildPath string

	// Path where the sockets are stored
	SocketsPath string

	// Path where the repository mirrors are stored
	GitMirrorsPath string

	// Seconds to wait before allowing git mirror clone lock to be acquired
	GitMirrorsLockTimeout int

	// Skip updating the Git mirror before using it
	GitMirrorsSkipUpdate bool `env:"BUILDKITE_GIT_MIRRORS_SKIP_UPDATE"`

	// Path to the buildkite-agent binary
	BinPath string

	// Path to the global hooks
	HooksPath string

	// Path to the plugins directory
	PluginsPath string

	// Paths to automatically upload as artifacts when the build finishes
	AutomaticArtifactUploadPaths string `env:"BUILDKITE_ARTIFACT_PATHS"`

	// A custom destination to upload artifacts to (for example, s3://...)
	ArtifactUploadDestination string `env:"BUILDKITE_ARTIFACT_UPLOAD_DESTINATION"`

	// Whether ssh-keyscan is run on ssh hosts before checkout
	SSHKeyscan bool

	// The shell used to execute commands
	Shell string

	// Phases to execute, defaults to all phases
	Phases []string

	// What signal to use for command cancellation
	CancelSignal process.Signal

	// List of environment variable globs to redact from job output
	RedactedVars []string

	// Backend to use for tracing. If an empty string, no tracing will occur.
	TracingBackend string

	// Service name to use when reporting traces.
	TracingServiceName string
}

func (*Config) ReadFromEnvironment

func (c *Config) ReadFromEnvironment(environ *env.Environment) map[string]string

ReadFromEnvironment reads configuration from the Environment, returns a map of the env keys that changed and the new values

type HookConfig

type HookConfig struct {
	Name           string
	Scope          string
	Path           string
	Env            *env.Environment
	SpanAttributes map[string]string
	PluginName     string
}