Document array input concatenation in surrounding arrays

What does this MR do and why?

When an array type input is used as one of the items in an array, its items are added to the surrounding array rather than nested inside it. This lets you reuse a shared list and extend it with additional items:

test_job:
  tags:
    - $[[ inputs.tags ]]
    - additional-tag

With an input value of [shared-tag-1, shared-tag-2], test_job uses [shared-tag-1, shared-tag-2, additional-tag].

This behavior was only shown in the needs examples, where it reads as a needs-specific trick rather than a general array input capability. The reference sections did not mention it:

  • Input types documented only the "entire YAML value" and "part of a larger string" placements.
  • Array type stated that !reference cannot be used, without pointing to what does work.

As a result, users looking for a way to reuse and extend a shared list across configuration files found a dead end exactly where they would look for the answer, and reached for !reference instead (see #606739 (closed)).

This MR documents the third placement in the Input types section, and links the Array type section to the array input and external file approach.

Related to #607053

Verification

The documented behavior was confirmed against the current implementation (Interpolation::Config#recursive_replace_array):

spec:
  inputs:
    tags:
      type: array
---
test_job:
  tags:
    - $[[ inputs.tags ]]
    - additional-tag
  script: ls

With tags: [shared-tag-1, shared-tag-2], test_job.tags resolves to ["shared-tag-1", "shared-tag-2", "additional-tag"].

MR acceptance checklist

  • Documented behavior verified against the implementation.
  • markdownlint and Vale passing.
  • Technical Writer review.

Merge request reports

Loading
Loading