Add default() interpolation function for CI/CD inputs
What does this MR do and why?
Adds a default interpolation function. It replaces an empty value with a fallback, so a component template can use its own version and still work when it is included at a branch or commit SHA:
spec:
component: [version, sha]
---
build:
image: registry.example.com/my-component:$[[ component.version | default(component.sha) ]]component.version is nil unless the component is included at a released version, which breaks templates (and their tests) that include the component at $CI_COMMIT_SHA.
The function is behind the ci_interpolation_default_function beta feature flag, disabled by default. Rollout issue: #638368
Proposed semantics (open for the group to confirm)
The issue has no agreed design yet, so this MR proposes one. Happy to change any of these:
- Syntax:
default('<literal>')ordefault(<context>.<field>), with parentheses liketruncate(0,7)andsplit(','). The issue description writesdefault component.sha, which would be new grammar for functions. - What counts as empty:
niland"".false,0and[]are real typed values and pass through. Onlynilis not enough, because string inputs are nevernil:Ci::Inputs::StringInput#coerced_valueturnsnilinto"". A nil-onlydefaultwould not help the cases from the issue comments, for example$[[ inputs.image_tag | default(component.version) ]]withimage_tag: { default: "" }.
Alignment with the existing functions
- The literal argument is single-quoted with no escape support, exactly like
split('<separator>'). - No whitespace inside the parentheses, like
split, the other function with a string argument.truncateallows whitespace around its integer arguments, but inside a quoted literal whitespace is part of the value, so the strictersplitform is less ambiguous. ^...$anchors and#{name}in the pattern, andinvalid argument: ...errors, as insplit.
Deviation: an access as an argument
No existing function takes a context access as an argument. default(component.sha) resolves its argument with the same Interpolation::Access and context as the block itself, so it accepts the same forms (inputs.name, component.sha, inputs.list[0]) and returns the same errors (for example unknown interpolation provided), prefixed with error in \default` function: invalid argument:. The argument is resolved even when the value is present, so a typo like default(component.shaa)` fails for every ref, not only for consumers who include the component at a SHA.
Other behaviour
- Chaining works with the existing stack:
$[[ inputs.tag | default(component.version) | default(component.sha) ]], within the limit of 3 functions per block. defaultmust come before string functions liketruncate, which return an error fornil. This is documented.- The fallback value is not interpolated again, the same as any input value.
- A literal cannot contain
|, becauseBlocksplits the block on|. Same limitation assplit('|'); documented. - The feature flag is checked only when an expression matches
default, so pipelines that do not use it do not evaluate the flag. This also avoids stubbing the flag across the external file specs, which thesplit()rollout needed. Security::CiConfiguration::BaseCreateServicenow loads the project's.gitlab-ci.ymlinsideGitlab::Ci::Config::FeatureFlags.with_actor(project), likeCloudSeed::GoogleCloud::GeneratePipelineServicealready does. Without it, a.gitlab-ci.ymlwith aspec:inputsheader that usesdefault()checks the flag with no actor, so a project-scoped enablement reads as disabled and creating the SAST or Secret Detection configuration MR fails. All other callers that interpolate a project's CI config already set an actor.
Possible follow-ups
Out of scope for this MR, error messages stay as they are:
- A hint for the bare
default <access>form, which the issue proposes. Todaydefault component.shaonly getsno function matching, with no pointer todefault(component.sha). - A clearer error for
|inside function arguments, shared withsplit. Todaydefault('a|b')reports the fragmentsdefault('aandb'). - On an unknown
component.*field, tell users to add the field tospec:component.
References
- #578504
- Feature flag rollout: #638368
- Origin of the proposal: #438275 (comment 2635308086)
- Precedent for a flagged function: !242134 (merged)
- Header interpolation for input defaults is a separate topic: #601160 (closed) and #606703
Screenshots or screen recordings
Not applicable, no UI change.
How to set up and validate locally
-
Enable the feature flag in the Rails console:
Feature.enable(:ci_interpolation_default_function) -
In a project, add a component at
templates/my-component/template.yml:spec: component: [version, sha] --- my-job: image: alpine:$[[ component.version | default('latest') ]] script: echo "$[[ component.version | default(component.sha) ]]" -
In another project, include it at a commit SHA and at a released version with
include: component: <host>/<path>/my-component@<ref>. -
Check the pipeline: at a SHA the job uses
alpine:latestand echoes the SHA. At a released version it uses the version.
MR acceptance checklist
Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.