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 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 NoProfile() bool
- func RetrieveScriptEnv() (string, error)
- func SchedulerLogDir() (dir string, found bool, err error)
- func SchedulerSignal() (string, bool, error)
- func SupportedPrefix(s string) bool
- func TrueEnvVar(key string) bool
- func UserVolumes(gen configure.General) (s []string, err error)
- func ValidRunnerVersion(major, minor int) bool
- func ValidateDirectory(dir string) (err error)
- type Credential
- type ExecutorEnv
- type GitInfo
- type Image
- type JobResponse
- 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" )
Variables ¶
This section is empty.
Functions ¶
func CustomBuildsDir ¶
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 ¶
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 KeyVarMapping ¶
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 NoProfile ¶ added in v0.18.0
func NoProfile() bool
NoProfile identifies if the user has requested "JACAMAR_NO_BASH_PROFILE" option.
func RetrieveScriptEnv ¶
RetrieveScriptEnv returns the full contents of a job script transferred via environment variables. An empty string will result in an error.
func SchedulerLogDir ¶
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 SchedulerSignal ¶ added in v0.17.0
SchedulerSignal returns the name or number of the signal that should be sent to the supported scheduler when a job is canceled. Any signal the is declared but contains non-alphanumeric characters will result in an error.
func SupportedPrefix ¶
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 ValidRunnerVersion ¶
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 ¶
ValidateDirectory ensures that proposed directory path meets Unix criteria and absolute. The existence of the directory is not required.
Types ¶
type Credential ¶ added in v0.19.0
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 and job response details that are necessary for the completion of a CI job.
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 against the job response during config_exec.
type JobResponse ¶
type JobResponse struct { ID int `json:"id"` Token string `json:"token"` GitInfo GitInfo `json:"git_info"` Image Image `json:"image"` Credentials []Credential `json:"credentials"` 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 `validate:"jwt"` }
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 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"` // ImageName user defined container - Optional ImageName string `key:"JACAMAR_CI_IMAGE_NAME" required:"false"` // ImageEntryPoint user defined (command separated) CLI entrypoint value (--entrypoint) - Optional ImageEntryPoint string `key:"JACAMAR_CI_IMAGE_ENTRYPOINT" required:"false"` // RegistryCredentials comma separated url:encoded credentials that can be inserted into // a container runtime auth file. Please use the DecodeRegistryCredentials to fetch - Optional RegistryCredentials string `key:"JACAMAR_CI_REGISTRY_CREDENTIALS" required:"false"` // PullPolicy the first user provided pull_policy for images, if provided. PullPolicy string `key:"JACAMAR_CI_PULL_POLICY" required:"false"` }
StatefulEnv maintains variables provided back to the runner during the configuration and made available to subsequent stages. Some values are not required and may only be present depending on your configuration.
func (StatefulEnv) DecodeRegistryCredentials ¶ added in v0.19.0
func (s StatefulEnv) DecodeRegistryCredentials() map[string]string
DecodeRegistryCredentials returns the decoded stateful credentials in a form (map[url]encodedAuth) that can be used by container runtime in auth files.