envparser

Documentation

Overview

Package envparser manages actions related to the retrieval and validation of key environment variables used by the GitLab Runner in order to provide context to a custom executor driver. The ideal scenario involves fetching the ExecutorEnv structure as early as possible during the job's preparation phase. Any missing required variables can lead to unexpected failures that should be avoided by strictly observing any error raised here.

Index

• Constants
• func CustomBuildsDir() (dir string, found bool, err error)
• func EstablishScriptEnv(contents string, maxEnvChars int) []string
• func ExitCodes() (sysExit, buildExit int)
• func GitTrace() bool
• func KeyVarMapping(i interface{}, env map[string]string) error
• func RetrieveScriptEnv() (string, error)
• func SchedulerLogDir() (dir string, found bool, err error)
• func SupportedPrefix(s string) bool
• func TrueEnvVar(key string) bool
• func ValidRunnerVersion(major, minor int) bool
• func ValidateDirectory(dir string) (err error)
• type ExecutorEnv
  • func Fetcher(stateReq bool, c arguments.ConcreteArgs, opt configure.Options) (je ExecutorEnv, err error)
• type GitInfo
• type JobResponse
  • func (j JobResponse) ExpandState(state *StatefulEnv)
• type RequiredEnv
• type RunnerInfo
• type StatefulEnv
• type Variable

Constants

const (
	// UserVarTagName defines the structure tag used to identify the associated environment
	// variable set by the runner.
	UserVarTagName = "key"
	// RequiredKey defines the structure tag indicating if an environment variable is
	// required. This should be observed, jobs without required variable(s) must fail.
	RequiredKey = "required"
)

Functions

func CustomBuildsDir

func CustomBuildsDir() (dir string, found bool, err error)

CustomBuildsDir retrieve and validate a user defined CUSTOM_BUILDS_DIR variable to be used in related directory identification and creation. The lack of any corresponding value is conveyed as a boolean and does not result in any error message. Unexpanded variables detected in the directory do not cause errors, and upon expansion the path should be re-validated.

func EstablishScriptEnv

func EstablishScriptEnv(contents string, maxEnvChars int) []string

EstablishScriptEnv splits the contents of a CI job script according to the maximum environment character length and set's every environment variable accordingly.

func ExitCodes

func ExitCodes() (sysExit, buildExit int)

ExitCodes returns both the SYSTEM_FAILURE_EXIT_CODE (default: 2) and BUILD_FAILURE_EXIT_CODE (default: 1) if defined by the custom executor. Uses default values if none found.

func GitTrace

func GitTrace() bool

GitTrace if Git's tracing/debug is expected.

func KeyVarMapping

func KeyVarMapping(i interface{}, env map[string]string) error

KeyVarMapping maps the expected key (struct tag UserVarTagName) to the established env map. Required values (struct tag RequiredKey) are observed. Only String types are supported in this workflow, any invalid field will result in an error message.

func RetrieveScriptEnv

func RetrieveScriptEnv() (string, error)

RetrieveScriptEnv returns the full contents of a job script transferred via environment variables. An empty string will result in an error.

func SchedulerLogDir

func SchedulerLogDir() (dir string, found bool, err error)

SchedulerLogDir retrieve and validate a user defined COPY_SCHEDULER_LOGS variable to be used in related directory identification and creation. The lack of any corresponding value is conveyed as a boolean and does not result in any error message.

func SupportedPrefix

func SupportedPrefix(s string) bool

SupportedPrefix ensures that the environment variable key provided has a supported prefix. This should be used to avoid sharing or closely analyzing environment variables not associated with the custom executor model. IMPORTANT: this does not guarantee security in cases where administratively defined variables match the prefix of runner defined ones.

func TrueEnvVar

func TrueEnvVar(key string) bool

TrueEnvVar check if variable 'true' or '1'.

func ValidRunnerVersion

func ValidRunnerVersion(major, minor int) bool

ValidRunnerVersion identify if the runner version triggering the job is valid against the provided major.minor release version. Since we check against custom environmental variables this should only be used as a smoke test to avoid later difficult errors and not as a security requirement.

func ValidateDirectory

func ValidateDirectory(dir string) (err error)

ValidateDirectory ensures that proposed directory path meets Unix criteria and absolute. The existence of the directory is not required.

Types

type ExecutorEnv

type ExecutorEnv struct {
	RequiredEnv
	StatefulEnv
	// JobResponse is a selected sub-set of variables and only available during configuration actions.
	JobResponse
}

ExecutorEnv maintains a view of all environment variables that are necessary for the completion of a CI job. All variables provided to the driver from the runner should remain available throughout the duration of the process.

func Fetcher

func Fetcher(
	stateReq bool,
	c arguments.ConcreteArgs,
	opt configure.Options,
) (je ExecutorEnv, err error)

Fetcher retrieves expected environment variables (required and stateful) and returns them via the ExecutorEnv struct. If any missing variables are detected (that are deemed required) an error message is returned. In addition, a range of validation steps are preformed based upon the CI stage, with expanded checks again the job response during config_exec.

type GitInfo

type GitInfo struct {
	RepoURL string `json:"repo_url"`
	Ref     string `json:"ref"`
	RefType string `json:"ref_type"`
	Sha     string `json:"sha"`
}

type JobResponse

type JobResponse struct {
	ID         int        `json:"id"`
	Token      string     `json:"token"`
	GitInfo    GitInfo    `json:"git_info"`
	Variables  []Variable `json:"variables"`
	RunnerInfo RunnerInfo `json:"runner_info"`
}

JobResponse maintains the structured via of the JSON provided to the runner by the server for the purposes of job execution. Though the entirety of the response is made available to the custom executor, only a small subset may be made available as we rely on the runner to realize the majority of the functionality. https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/common/network.go

func (JobResponse) ExpandState

func (j JobResponse) ExpandState(state *StatefulEnv)

ExpandState utilizes select elements of the server's response payload to expand the stateful variables during the config_exec stage.

type RequiredEnv

type RequiredEnv struct {
	JobID        string `key:"CUSTOM_ENV_CI_JOB_ID"  validate:"number" required:"true"`
	JobToken     string `key:"CUSTOM_ENV_CI_JOB_TOKEN"  validate:"authToken" required:"true"`
	ConcurrentID string `key:"CUSTOM_ENV_CI_CONCURRENT_ID"  validate:"number,max=5" required:"true"`
	RunnerShort  string `key:"CUSTOM_ENV_CI_RUNNER_SHORT_TOKEN"  validate:"authToken" required:"true"`
	ServerURL    string `key:"CUSTOM_ENV_CI_SERVER_URL" validate:"url" required:"true"`
	CIJobJWT     string `key:"CUSTOM_ENV_CI_JOB_JWT" validate:"jwt" required:"true"`
}

RequiredEnv identifies variables from the CustomEnv for easy retrieval. During configuration Jacamar-Auth take additional steps to validate all variables, so they can be trusted during subsequent stages/processes. Please note this validation does not ensure values will work, only that they are sufficiently free of user influence and potentially malicious values.

type RunnerInfo

type RunnerInfo struct {
	Timeout int `json:"timeout"`
}

type StatefulEnv

type StatefulEnv struct {
	// BaseDir UserContext.BaseDir - Required
	BaseDir string `key:"JACAMAR_CI_BASE_DIR" required:"true"`
	// BuildsDir UserContext.BuildsDir - Required
	BuildsDir string `key:"JACAMAR_CI_BUILDS_DIR" required:"true"`
	// CacheDir UserContext.CacheDir - Required
	CacheDir string `key:"JACAMAR_CI_CACHE_DIR" required:"true"`
	// ScriptDir UserContext.ScriptDir - Required
	ScriptDir string `key:"JACAMAR_CI_SCRIPT_DIR" required:"true"`
	// Username UserContext.UserName - Required
	Username string `key:"JACAMAR_CI_AUTH_USERNAME" required:"true"`
	// SharedGroup UserContext.SharedGroup - Optional
	SharedGroup string `key:"JACAMAR_CI_SHARED_GROUP" required:"false"`
	// ProjectPath JWT.project_path - Optional
	ProjectPath string `key:"JACAMAR_CI_PROJECT_PATH" required:"false"`
	// RunnerTimeout maximum job timeout identified in job response - Required
	RunnerTimeout string `key:"JACAMAR_CI_RUNNER_TIMEOUT" required:"true"`
}

StatefulEnv maintains variables provided back to the runner during the configuration that are then made available to subsequent stages. Some values are not required and may only be present depending on your configuration.

type Variable

type Variable struct {
	Key   string `json:"key"`
	Value string `json:"value"`
}