Properly handle !reference in CI/CD inputs

Updated plan

Instead of enabling !reference tag support in inputs, we are:

• Documenting how to achieve the same outcome by using array input concatenation
• Explicitely rejecting the reference tag in inputs as opposed to dumping the internal representation into the merged YAML

Former description

Proposal

Support !reference in CI/CD components/pipeline inputs for array-type inputs, enabling configuration reuse across components.

Current Behavior

!reference tags are explicitly unsupported in array-type inputs. When used, they are not resolved during input interpolation, resulting in:

• Nested arrays: [[\"hello\", \"world\"], \"other\"] instead of [\"hello\", \"world\", \"other\"]
• Leaked Ruby objects in the configuration (see #606739 (closed))

Technical Context

Input interpolation runs before !reference tag resolution in the config loading pipeline. When a !reference is inside an array input value, it reaches interpolation as an unresolved object and gets stringified before the tag resolver ever sees it.

Related MR !247355 (closed) adds validation to reject unresolved YAML tags in array inputs with a clear error message.

Implementation Approach

Recommended: Option 1 — Allow !reference only as the entire input value

Allow !reference when it is the sole value of an array input, not nested within an array:

# ✅ Supported
include:
  - component: path/to/component@version
    inputs:
      my-array: !reference[.my-shared-inputs]

# ❌ Not supported (will show clear error)
include:
  - component: path/to/component@version
    inputs:
      my-array:
        - !reference[.my-shared-inputs]
        - other

This approach:

• Avoids complex flattening logic
• Preserves the ability to use !reference in script, before_script, after_script, and rules (which already work due to inherent inlining)
• Provides a clear, intuitive behavior

Acceptance Criteria

• my-array: !reference[.foo] resolves the reference and uses the referenced array as the input value
• my-array: [!reference[.foo], other] shows a clear error message explaining that !reference is not supported in nested array positions
• Default values with nested !reference are also rejected with the same error
• Unit tests cover both valid and invalid cases
• Integration tests confirm the resolved reference is correctly interpolated into jobs
• Documentation is updated to clarify when !reference is supported in array inputs
• Error message guides users to the documentation

Dependencies

• Blocked by !247355 (closed) (adds validation to reject unresolved YAML tags)

Files Likely to Change

• lib/gitlab/ci/inputs/array_input.rb — validation logic
• lib/gitlab/ci/config/interpolation/interpolator.rb — interpolation handling
• doc/ci/inputs/_index.md — documentation
• doc/ci/yaml/yaml_optimization.md — !reference tag documentation
• Test files for the above modules