Struggling to make use of 'include' w/reference maps

I see that the documentation specifically calls out that you may have to use ‘!reference’ syntax, but it doesn’t demonstrate it for a <</extends scenario.

I’m trying to create some separation of concerns rather than having one single .yml file, but cannot seem to get it to work.

We have a mono-repos so developed a pattern of having runner descriptions that we use as the base for jobs, coupled with a hidden generalized job description, and at the end we merge these to produce the per-platform/config jobs (smoke build windows, smoke build macos)

# Referenceable definitions of the runners for platform specificity.
  macos: &macos-runner
    tags: [ macos ]
    HostOS: macos
    Generator: ninja

  windows: &windows-runner
    tags: [ windows ]
      HostOS: windows
      Generator: vs2019

# The platform-agnostic core definition of the smoke build job.
.smoke build:
  stage: build
    - changes:
      - src/*
    - tools/
    - tools/
    - tools/

# The actual jobs:
smoke build macos:
  <<: *macos-runner
  extends: .smoke build

smoke build windows:
  <<: *windows-runner
  extends: .smoke build

My naive hope was I could split this up with the runner defs in the top-level file or a file it included, and then include the per-subproject .yml. This does not work (you get an error that the include file has invalid yaml syntax and no details). I assume because the map reference cannot find “macos-runner” etc.

So I tried having .gitlab.yml include just the per-subproject include and the per-subproject include include the runners.yml. This also does not work, and again just tells me the include has invalid yaml syntax end of message. Again assume it cannot find the “macos-runner” (this is the error that trying to load the file with PyYaml produces).

The instructions give the impression that you ought to be able to do:

smoke build macos:
  <<: !reference [ .RunnerDefs, macos ]

(or macos-runners). Neither works, logically, because this isn’t valid yaml.

Have I taken a wrong path here?