feat(pipeline): a need on a job an include creates carries optional: true

Andrew Dunnrequested to merge
standards/needs-optional into main

What does this MR do and why?

Adds one pipeline assertion: a needs: entry in .gitlab-ci.yml that names a job the file does not itself define carries optional: true. A job the file does not define can only come from an included component, and the component's rules decide whether that job exists on a given pipeline source. Without optional: true, a pipeline on a source the include's rules do not cover fails creation outright rather than running without the job. topology 0.3.0 hit exactly this: pages needed the included freshness-heartbeat job unconditionally and no web or api pipeline could be created; 0.3.1 made the need optional. The catalog side of the same rule landed in pipeline!171 (merged) (every component either runs on every source or its README carries a fixed notice telling consumers to mark the need optional).

References

Standards affected

standards/pipeline: new assertion needs-optional:.gitlab-ci.yml, implemented as check_needs_optional() in _lib.sh and registered in scripts/guard-checks.sh's primitive whitelist. standards/pipeline/check.sh calls it beside the existing catalog-pin and merge-request-validation assertions. standards/pipeline/SKILL.md's Verify block is regenerated with just sync-verify, and a "Needs on jobs an include creates" block states the rule, that trigger: jobs are parsed like any other job, and the exemption shape. No standard changes status.

Exemption implications

A consumer whose need must fail rather than skip when the target job is absent registers an exemption in its own .reference.yaml:

- standard: pipeline
  assertion: needs-optional:.gitlab-ci.yml
  reason: |
    <why this need must stay non-optional>

No existing .reference.yaml needs a field change. Four consumers currently carry needs on included jobs without optional: true, each against a catalog container, binary or attest job: kaniko, postern, storyping and platform-one/p1-vp-generator. None is edited here; each gets its own follow-up MR.

Test plan

  • just guard passes locally
  • just check passes locally (self-conformance)
  • just build && just agent succeeds (full pre-deploy gate)
  • check.sh ran read-only against the twenty estate consumers; findings above
  • If templates/ changed: not applicable
  • If design/ changed: not applicable

Reviewer checklist

  • Voice is GitLab Inc. neutral (no solo-developer narrative, no decorative essays)
  • No em-dashes in customer-facing prose
  • No filler words ("comprehensive", "robust", "leverage", "seamless")
  • Trailers present (Signed-off-by:, Changelog: if user-visible, AI-Assisted:/AI-Tools: if applicable)
  • CODEOWNERS section matches paths touched
  • Not breaking for consumers: the assertion fires only on a shape that already fails pipeline creation on some source

Merge request reports