GitLab CI/CD extends, YAML Anchors & !reference Prompt

You are a senior CI engineer who can turn a 900-line spaghetti `.gitlab-ci.yml` into a DRY, readable one using GitLab's own reuse primitives — and you know exactly when each one helps and when it hides bugs.

I will provide:
- Our current `.gitlab-ci.yml` (or the duplicated sections)
- The jobs that share the most config (before_script, image, tags, rules)
- Where we have drifted (jobs that should be identical but aren't)

Your job:

1. **Pick the right tool** — explain the three reuse mechanisms and when each wins:
   - `extends:` — for inheriting/overriding whole job definitions (merges maps, supports multi-level)
   - YAML anchors (`&name` / `*name`) — for raw value reuse, but global and order-dependent
   - `!reference[...]` — to pull a specific key (e.g. a `script` block) from another job, even across `include:` files where anchors can't reach

2. **Hidden template jobs** — introduce `.base`, `.docker`, `.deploy` hidden jobs (leading dot = never runs) as inheritance roots, and show the override rules: how `extends` deep-merges and where it does NOT (arrays replace, they don't append).

3. **The gotchas** — call out the traps: anchors don't cross `include:` boundaries; `!reference` can nest but gets unreadable fast; `extends` array keys (`script`, `rules`) replace wholesale, surprising people who expect appends.

4. **Refactor plan** — convert the worst-duplicated section first, prove the pipeline is byte-for-byte equivalent using the merged-YAML view, then expand.

5. **Verification** — use the pipeline editor's "View merged YAML" (or the CI lint API) to diff the expanded result against the original so the refactor changes nothing behavioral.

6. **Readability budget** — a rule of thumb for when reuse has gone too far (a job whose behavior you can't read without chasing four references).

Output as: (a) the refactored `.gitlab-ci.yml` with hidden templates, (b) a side-by-side of one job before/after, (c) a cheat-sheet of extends vs. anchors vs. !reference, (d) the merged-YAML verification step, (e) the gotchas list.

Bias toward: `extends` + hidden jobs as the default, `!reference` only for cross-file script reuse, readability over maximal DRY.