env

package
v3.136.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 4, 2026 License: MIT Imports: 10 Imported by: 5

Documentation

Overview

Package env provides utilities for dealing with environment variables.

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

Index

Constants

View Source 
const (
	// OTELTracesEndpoint, OTELTracesProtocol and OTELTracesHeaders are the
	// standard OTel SDK signal-specific exporter variables used for delivery.
	// Traces-specific rather than generic, so the exporter credential cannot
	// be picked up by another signal (e.g. a logs exporter pointed at a
	// pipeline-chosen endpoint) through the generic-variable fallback.
	OTELTracesEndpoint = "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT"
	OTELTracesProtocol = "OTEL_EXPORTER_OTLP_TRACES_PROTOCOL"
	OTELTracesHeaders  = "OTEL_EXPORTER_OTLP_TRACES_HEADERS"
)

Control-plane OTLP exporter delivery: when agent registration supplies an OTLP trace exporter (endpoint, protocol, and possibly credentialed headers), the job runner delivers it to the bootstrap process through the standard traces-specific OTel SDK variables below. Hooks, plugins, and the job command inherit them, so job-level ("userspace") OTel tooling can join the agent's trace via the propagated traceparent and export its spans to the same collector — that pass-through is the point of the feature. Design: https://linear.app/buildkite/issue/A-1641

Variables

View Source 
var CheckoutOverrideModeNames = []string{
	string(CheckoutOverrideStrict),
	string(CheckoutOverrideFromJob),
	string(CheckoutOverrideNone),
}

CheckoutOverrideModeNames lists the accepted flag/env values, strictest first.

View Source 
var OTLPDestinationVars = []string{
	"OTEL_EXPORTER_OTLP_ENDPOINT",
	"OTEL_EXPORTER_OTLP_HEADERS",
	OTELTracesEndpoint,
	OTELTracesHeaders,
}

OTLPDestinationVars are the variables whose presence — even with an empty value — counts as an existing OTLP destination choice: whoever set one made a decision about where trace data (or its credentials) go. A destination in the agent's own environment makes registration ignore the server exporter entirely (see agent.HasLocalOTLPDestination); a destination in a job's backend env makes the job runner skip injection for that job. Both checks are all-or-nothing so a server credential is never sent to a locally- or pipeline-chosen endpoint, nor a local credential to the server's endpoint. Protocol-, certificate- or timeout-only variables deliberately do not count as a destination.

Functions

func IsCheckoutLocked added in v3.134.0 

func IsCheckoutLocked(name string, mode CheckoutOverrideMode) bool

IsCheckoutLocked reports whether a checkout-scoped var is locked against the job's within-job configuration sources (hooks, plugins, and the Job API) under the given mode. Only strict locks these; from-job and none let the job configure its own checkout. The backend job env (pipeline/step env) and secrets are external sources locked in every mode except none, governed separately (see IsCheckoutLockedForSecrets and createEnvironment in agent/job_runner.go); vars that aren't checkout-scoped are governed by IsProtected / IsProtectedFromWithinJob.

func IsCheckoutLockedForJobEnv added in v3.134.0 

func IsCheckoutLockedForJobEnv(name string, mode CheckoutOverrideMode) bool

IsCheckoutLockedForJobEnv reports whether a checkout-scoped var is locked against the backend job env (pipeline/step env) under the given mode. Most scoped vars follow the secrets rule (locked unless none; see IsCheckoutLockedForSecrets), but the vars in checkoutJobEnvFromJobFloor have a from-job floor: the backend job env may set them under from-job too, and only strict locks them. Vars that aren't checkout-scoped are governed by IsProtected instead.

func IsCheckoutLockedForSecrets added in v3.134.0 

func IsCheckoutLockedForSecrets(name string, mode CheckoutOverrideMode) bool

IsCheckoutLockedForSecrets reports whether a checkout-scoped var is locked against secret-to-env mappings under the given mode. Secrets are an external source, so both strict and from-job block them; only none lets a secret set checkout config. The backend job env is mostly the same (enforced in createEnvironment, agent/job_runner.go), except that under from-job it still lets pipeline/step env set the submodules/skip-checkout/skip-fetch/timeout toggles on their default side to match historical behaviour, and set the sparse-checkout paths and mode outright (see IsCheckoutLockedForJobEnv); secrets have no such history, so they stay blocked. Vars that aren't checkout-scoped are governed by IsProtected instead.

func IsCheckoutOverrideScoped added in v3.134.0 

func IsCheckoutOverrideScoped(name string) bool

IsCheckoutOverrideScoped reports whether the environment variable is a checkout-related var whose write-protection depends on the checkout-override mode. Whether it's actually locked for a given source is decided by IsCheckoutLocked (the job's own config sources) and IsCheckoutLockedForSecrets.

func IsProtected added in v3.106.0 

func IsProtected(name string) bool

IsProtected reports whether the environment variable is write-protected when the write is coming from job-level env or secrets.

func IsProtectedFromWithinJob added in v3.124.0 

func IsProtectedFromWithinJob(name string) bool

IsProtectedFromWithinJob reports whether the environment variable is write- protected when the write is coming from within the job (including hooks and plugins).

func SeqSlice added in v3.127.1 

func SeqSlice(s []string) iter.Seq2[string, string]

SeqSlice returns an iterator over all name/value pairs of env vars in a slice of strings.

func Split added in v3.40.0 

func Split(l string) (name, value string, ok bool)

Split splits an environment variable (in the form "name=value") into the name and value substrings. If there is no '=', or the first '=' is at the start, it returns `"", "", false`.

Types

type CheckoutOverrideMode added in v3.134.0 

type CheckoutOverrideMode string

CheckoutOverrideMode controls how much of the agent's checkout configuration a job may override. It applies only to checkoutOverrideScope vars; protectedEnv membership is independent of the mode. Its value is the flag/env string. 

const (
	// CheckoutOverrideFromJob is the default and matches the agent's historical
	// behaviour: the job may configure its own checkout from within-job sources
	// (hooks, plugins, and the Job API), overriding agent config. The backend job
	// env (pipeline/step env) and secrets may not override the checkout flags,
	// which the agent always emits. The submodules/skip-checkout/skip-fetch/timeout
	// toggles are emitted by the agent only on their non-default side, so backend
	// job env can still set those when the agent leaves them at their default, as
	// on main (secrets are blocked from all of them; see IsCheckoutLockedForSecrets).
	// strict closes that toggle gap.
	CheckoutOverrideFromJob CheckoutOverrideMode = "from-job"

	// CheckoutOverrideStrict locks the checkoutOverrideScope vars against every
	// source: pipeline/step env, secrets, hooks, plugins, and the Job API. Vars
	// outside that scope (see the exclusions note on checkoutOverrideScope) are
	// unaffected by the mode.
	CheckoutOverrideStrict CheckoutOverrideMode = "strict"

	// CheckoutOverrideNone lets any source, including secrets, override the
	// checkout-override-scoped vars. Vars that are always agent-authoritative
	// (the mirror-infra vars and SUBMODULE_CLONE_CONFIG in protectedEnv) are
	// unaffected by the mode, so they stay locked even under none.
	CheckoutOverrideNone CheckoutOverrideMode = "none"
)

func ParseCheckoutOverrideMode added in v3.134.0 

func ParseCheckoutOverrideMode(s string) (CheckoutOverrideMode, error)

ParseCheckoutOverrideMode maps a flag/env value to a mode. An empty string selects the default (from-job).

func (CheckoutOverrideMode) RestrictedForCommandEval added in v3.134.0 

func (m CheckoutOverrideMode) RestrictedForCommandEval(commandEvalEnabled bool) CheckoutOverrideMode

RestrictedForCommandEval tightens the mode so command-eval can't be bypassed: when command-eval is disabled, it returns CheckoutOverrideStrict so no source (pipeline/step env, secrets, hooks, plugins, or the Job API) can inject git flags that would otherwise circumvent no-command-eval. Otherwise it returns the mode unchanged.

func (CheckoutOverrideMode) String added in v3.134.0 

func (m CheckoutOverrideMode) String() string

type Diff added in v3.33.0 

type Diff struct {
	Added   map[string]string
	Changed map[string]DiffPair
	Removed map[string]struct{}
}

func (*Diff) Empty added in v3.33.0 

func (diff *Diff) Empty() bool

func (*Diff) Keys added in v3.124.0 

func (diff *Diff) Keys(yield func(string) bool)

Keys is an iterator over all env vars present in a diff.

func (*Diff) Remove added in v3.33.0 

func (diff *Diff) Remove(key string)

type DiffPair added in v3.33.0 

type DiffPair struct {
	Old string
	New string
}

type Environment 

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

Environment is a map of environment variables, with the keys normalized for case-insensitive operating systems

func FromMap added in v3.45.0 

func FromMap(m map[string]string) *Environment

func FromSlice 

func FromSlice(s []string) *Environment

FromSlice creates a new environment from a string slice of KEY=VALUE

func New 

func New() *Environment

func NewWithLength added in v3.45.0 

func NewWithLength(length int) *Environment

func (*Environment) Apply added in v3.33.0 

func (e *Environment) Apply(diff Diff)

func (*Environment) Copy 

func (e *Environment) Copy() *Environment

Copy returns a copy of the env

func (*Environment) Diff 

func (e *Environment) Diff(other *Environment) Diff

Diff returns a new environment with the keys and values from this environment which are different in the other one.

func (*Environment) Dump added in v3.45.0 

func (e *Environment) Dump() map[string]string

Dump returns a copy of the environment with all keys normalized

func (*Environment) DumpPairs added in v3.75.0 

func (e *Environment) DumpPairs() []Pair

DumpPairs returns a copy of the environment with all keys normalised.

func (*Environment) Exists 

func (e *Environment) Exists(key string) bool

Exists returns true/false depending on whether or not the key exists in the env

func (*Environment) Get 

func (e *Environment) Get(key string) (string, bool)

Get returns a key from the environment

func (*Environment) GetBool 

func (e *Environment) GetBool(key string, defaultValue bool) bool

Get a boolean value from environment, with a default for empty. Supports true|false, on|off, 1|0

func (*Environment) GetInt added in v3.98.0 

func (e *Environment) GetInt(key string, defaultValue int) int

GetInt gets an int value from environment, with a default for unset, empty, or invalid values.

func (*Environment) GetString added in v3.98.0 

func (e *Environment) GetString(key, defaultValue string) string

GetString gets a string value from environment, with a default for unset or empty values.

func (*Environment) Length 

func (e *Environment) Length() int

Length returns the length of the environment

func (*Environment) MarshalJSON added in v3.40.0 

func (e *Environment) MarshalJSON() ([]byte, error)

func (*Environment) Merge 

func (e *Environment) Merge(other *Environment)

Merge merges another env into this one and returns the result

func (*Environment) Remove 

func (e *Environment) Remove(key string) string

Remove a key from the Environment and return its value

func (*Environment) Set 

func (e *Environment) Set(key, value string)

Set sets a key in the environment

func (*Environment) ToSlice 

func (e *Environment) ToSlice() []string

ToSlice returns a sorted slice representation of the environment

func (*Environment) UnmarshalJSON added in v3.40.0 

func (e *Environment) UnmarshalJSON(data []byte) error

type Pair added in v3.75.0 

type Pair struct{ Name, Value string }

Pair is an environment variable name/value pair.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.