### Release notes When a Pipeline Execution Policy (or any wrapper config) uses `include: ref: $VARIABLE` with a wrapper-defined variable that has a declared `value:` default, the Run Pipeline UI form on consumer projects does not surface the prefilled variables defined in the included file. This proposal surfaces those variables in the form by resolving the `include: ref:` against the declared `value:` default for prefill purposes only. ### Problem to solve Platform teams who use Pipeline Execution Policies (or Compliance Frameworks) to inject a centrally-managed "factory" pipeline into many consumer projects need both: - Version pinning of the factory: a wrapper that uses `include: ref: $FACTORY_REF` so teams can pin to a specific factory version during testing or rollback while defaulting to `master` for production. - UI discoverability: the prefilled variables defined in the factory's `.gitlab-ci.yml` (`description:`, `value:`, `options:`) must be visible and editable in the Run Pipeline form on the consumer project, so users can discover and override pipeline inputs without external documentation. Today, when `ref:` uses a wrapper-defined variable (even one with a declared `value:` default), GitLab cannot statically resolve the included file at pipeline-creation time. The result: only `FACTORY_REF` itself is shown in the Run Pipeline form — none of the variables defined in the included factory `.gitlab-ci.yml` are visible. With a hardcoded `ref: master`, those same variables appear correctly. This forces platform teams to choose between: - Hardcode the `ref:` and lose the ability to test against different factory versions, or - Use a variable `ref:` and lose UI discoverability of all pipeline inputs for consumers. This is the documented behaviour of `include:` variable expansion (see [Use variables with include](https://docs.gitlab.com/ci/yaml/includes/#use-variables-with-include)) — wrapper-level `variables:` blocks are not in the supported list because `include:` is processed before the wrapper's `variables:` are evaluated. The proposal here is to handle the prefill case as a separate pre-pass. ### Proposal Extend `Ci::ListConfigVariablesService` to support a "prefill resolution" mode that resolves `include: ref:` against the declared `value:` defaults in the wrapper's `variables:` block, exclusively for the purpose of populating the Run Pipeline form. Behaviour: - The actual pipeline creation path is unchanged. At runtime, `include:` is resolved against whatever value the user supplies (or the wrapper's default, if none is supplied). - The Run Pipeline form pre-pass reads the wrapper's `variables:` block first, picks out declared `value:` defaults, then resolves `include: ref:` against those defaults to fetch and parse the included file's prefilled variables. - The form displays both the wrapper's variables (e.g. `FACTORY_REF`) and the included file's variables (e.g. factory inputs), with the included variables clearly labelled as "shown for default ref `<value>`". - Cached and pre-parsed at policy-save time where possible, similar to the approach used in [#527021 (closed)](https://gitlab.com/gitlab-org/gitlab/-/issues/527021) / [!207861 (merged)](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/207861). - Gated behind a feature flag during rollout. #### Example wrapper ```yaml variables: FACTORY_REF: value: 'master' description: 'Branch or tag of the factory to include' include: - project: 'my-group/sdlc-factory' ref: $FACTORY_REF file: '.gitlab-ci.yml' ``` Today: only `FACTORY_REF` shows up in the Run Pipeline form on consumer projects. Expected: `FACTORY_REF` shows up, and so do all the variables declared in `my-group/sdlc-factory@master/.gitlab-ci.yml`. ### How this is different from existing work - [&20356 Support passing inputs from project to pipeline execution policy jobs](https://gitlab.com/groups/gitlab-org/-/work_items/20356) introduces `.gitlab/policy-inputs.gitlab-ci.yml` for projects to pass values to PEP `spec: inputs:`. That epic addresses input-value injection but does not solve dynamic-`ref:` resolution. `ref:` swaps which file is included (potentially a different commit with different jobs / variables), not just values inside one file. The epic also lists "UI integration" as an open question, not a committed deliverable. - [#527021 (closed)](https://gitlab.com/gitlab-org/gitlab/-/issues/527021) (shipped in 18.5) surfaces prefilled variables defined directly inside a PEP's CI config in the Run Pipeline form — but it relies on the policy's `include:` being statically resolvable. The same architectural assumption is what this proposal asks to relax for the prefill-only path. ### Implementation considerations A few real costs that should be factored into prioritization: 1. Ordering inversion. Today `include:` is processed before the wrapper's `variables:` block. The prefill pre-pass needs to read `variables:` first, pick declared defaults, then resolve `include:`. This is a parallel evaluation pipeline for the form, separate from the actual pipeline-creation path. 2. Two divergent realities. The variable resolved for the form (declared default) and the variable resolved at pipeline creation (whatever the user actually picks) can diverge arbitrarily. UX needs to communicate that the form shows variables for the default ref, not the eventual run. 3. Performance and caching. Resolving an external `include:` against a non-default ref means a Gitaly fetch from a different project on a different ref, which is what the original 17.x design avoided. The pre-parse-and-persist pattern from [#527021 (closed)](https://gitlab.com/gitlab-org/gitlab/-/issues/527021) likely applies here since the wrapper's `value:` default is stable. 4. Trust boundary. When `include:` resolves dynamically to a different project / ref, the user opening the Run Pipeline form may not have read access there. The current static-resolution path implicitly enforces this; the prefill pre-pass needs its own access check before exposing variable names and descriptions. 5. Recursion. If the included file itself uses `include:` with a variable, the same pre-pass logic recurses. Solvable but needs bounds-checking. ### Intended users - Platform engineering teams running centrally-managed CI/CD pipelines via Pipeline Execution Policies or Compliance Frameworks across many consumer projects. - Application teams running pipelines on consumer projects who need to discover and override pipeline inputs without external documentation. ### Feature Usage Metrics - Number of projects whose Run Pipeline form rendered prefilled variables resolved via dynamic `include: ref:`. - Number of PEPs / wrappers whose `include: ref:` is parameterized (vs. hardcoded). - Adoption funnel: feature-flag rollout percentages and opt-in behaviour. ### Does this feature require an audit event? N/A ### Customer Impact An Ultimate Dedicated customer is building a centrally-managed factory pipeline using a single golden-source repository consumed via `include:` from a thin wrapper file injected through Pipeline Execution Policies into consumer projects. The current behaviour blocks them from getting both version pinning and UI discoverability. ### Ticket [Ticket 715922](https://gitlab.zendesk.com/agent/tickets/715922) (GitLab Internal) cc @g.hickman @mcavoj