Documentation
¶
Overview ¶
Package env provides utilities for dealing with environment variables.
It is intended for internal use by buildkite-agent only.
Index ¶
- Variables
- func IsCheckoutLocked(name string, mode CheckoutOverrideMode) bool
- func IsCheckoutLockedForJobEnv(name string, mode CheckoutOverrideMode) bool
- func IsCheckoutLockedForSecrets(name string, mode CheckoutOverrideMode) bool
- func IsCheckoutOverrideScoped(name string) bool
- func IsProtected(name string) bool
- func IsProtectedFromWithinJob(name string) bool
- func SeqSlice(s []string) iter.Seq2[string, string]
- func Split(l string) (name, value string, ok bool)
- type CheckoutOverrideMode
- type Diff
- type DiffPair
- type Environment
- func (e *Environment) Apply(diff Diff)
- func (e *Environment) Copy() *Environment
- func (e *Environment) Diff(other *Environment) Diff
- func (e *Environment) Dump() map[string]string
- func (e *Environment) DumpPairs() []Pair
- func (e *Environment) Exists(key string) bool
- func (e *Environment) Get(key string) (string, bool)
- func (e *Environment) GetBool(key string, defaultValue bool) bool
- func (e *Environment) GetInt(key string, defaultValue int) int
- func (e *Environment) GetString(key, defaultValue string) string
- func (e *Environment) Length() int
- func (e *Environment) MarshalJSON() ([]byte, error)
- func (e *Environment) Merge(other *Environment)
- func (e *Environment) Remove(key string) string
- func (e *Environment) Set(key, value string)
- func (e *Environment) ToSlice() []string
- func (e *Environment) UnmarshalJSON(data []byte) error
- type Pair
Constants ¶
This section is empty.
Variables ¶
var CheckoutOverrideModeNames = []string{ string(CheckoutOverrideStrict), string(CheckoutOverrideFromJob), string(CheckoutOverrideNone), }
CheckoutOverrideModeNames lists the accepted flag/env values, strictest first.
Functions ¶
func IsCheckoutLocked ¶
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 ¶
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 ¶
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 ¶
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 ¶
IsProtected reports whether the environment variable is write-protected when the write is coming from job-level env or secrets.
func IsProtectedFromWithinJob ¶
IsProtectedFromWithinJob reports whether the environment variable is write- protected when the write is coming from within the job (including hooks and plugins).
Types ¶
type CheckoutOverrideMode ¶
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 ¶
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 ¶
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 ¶
func (m CheckoutOverrideMode) String() string
type Diff ¶
type Diff struct {
Added map[string]string
Changed map[string]DiffPair
Removed map[string]struct{}
}
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 ¶
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 ¶
func NewWithLength(length int) *Environment
func (*Environment) Apply ¶
func (e *Environment) Apply(diff Diff)
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 ¶
func (e *Environment) Dump() map[string]string
Dump returns a copy of the environment with all keys normalized
func (*Environment) DumpPairs ¶
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 ¶
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 ¶
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 ¶
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 ¶
func (e *Environment) UnmarshalJSON(data []byte) error
Source Files