Draft: Document spec:include behavior in included files

What does this MR do and why?

spec:include locations do not resolve the way the docs say. A local: location resolves against the file that added the include: keyword, not against the file that declares spec. The spec:include reference links local to include:local, which is defined as the same repository and branch as the file containing the include keyword. So the docs promise behavior we do not implement.

spec was only meant for inputs in the pipeline configuration file. Using it in a file that is itself added with include: was never a supported use case, but it has picked up usage. Changing the resolution now would break those pipelines, so we document the current behavior instead and mark the use case as unsupported.

This MR:

• Adds a topic to the inputs page that describes the actual resolution, with an example and the nesting-depth difference.
• Adds a bullet to the spec:include reference that calls out the difference from include:local and links to the new topic.

References

• #590532
• #606741 (closed)
• Behavior source: lib/gitlab/ci/config/external/file/base.rb, where the spec header is loaded with the parent context while include: uses the expanded context.

How to set up and validate locally

Docs only. Rendered output can be checked with the docs site build.