job

Documentation

Overview

package job 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(e *Executor, env *env.Environment) map[string]any
• func Merge(maps ...map[string]any) map[string]any
• type Executor
  • func New(conf ExecutorConfig) *Executor
  • func (e *Executor) Cancel() error
  • func (e *Executor) CheckoutPhase(ctx context.Context) error
  • func (e *Executor) CommandPhase(ctx context.Context) (hookErr error, commandErr error)
  • func (e *Executor) PluginPhase(ctx context.Context) error
  • func (e *Executor) Run(ctx context.Context) (exitCode int)
  • func (e *Executor) VendoredPluginPhase(ctx context.Context) error
• type ExecutorConfig
  • func (c *ExecutorConfig) ReadFromEnvironment(environ *env.Environment) map[string]string
• type HookConfig

Functions

func DDTracingExtras

func DDTracingExtras() map[string]any

func GenericTracingExtras

func GenericTracingExtras(e *Executor, env *env.Environment) map[string]any

func Merge

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

Types

type Executor

type Executor struct {
	// ExecutorConfig provides the executor configuration
	ExecutorConfig
	// contains filtered or unexported fields
}

Executor 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 job executor was a shell script, but was ported to Go for portability and testability.

func New

func New(conf ExecutorConfig) *Executor

New returns a new executor instance

func (*Executor) Cancel

func (e *Executor) Cancel() error

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

func (*Executor) CheckoutPhase

func (e *Executor) CheckoutPhase(ctx context.Context) error

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

func (*Executor) CommandPhase

func (e *Executor) CommandPhase(ctx context.Context) (hookErr error, commandErr error)

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

func (*Executor) PluginPhase

func (e *Executor) 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 (*Executor) Run

func (e *Executor) Run(ctx context.Context) (exitCode int)

Run the job and return the exit code

func (*Executor) VendoredPluginPhase

func (e *Executor) VendoredPluginPhase(ctx context.Context) error

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

type ExecutorConfig

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

	// The ID of the job being run
	JobID string

	// If the executor 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 job
	AgentName string

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

	// Should the executor 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

	// Should we enforce that only one checkout and one command hook are run?
	StrictSingleHooks 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

	// Amount of time to wait between sending the CancelSignal and SIGKILL to the process groups
	// that the executor starts. The subprocesses should use this time to clean up after themselves.
	SignalGracePeriod time.Duration

	// 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 (*ExecutorConfig) ReadFromEnvironment

func (c *ExecutorConfig) 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
}