Qv Nx CI

Nx CI — consolidated per-package workflows

Per-package CI is consolidated into generic -nx.yml leaves. Each package declares its CI shape as data in packages/<pkg>/project.json under targets.<target>.options.ci; Nx computes the affected set and .github/actions/nx-project-matrix turns each affected package's options.ci into a GitHub Actions matrix that the leaf fans out over.

Full reference (wiring diagram, options.ci cheat-sheet, fork-safety model): docs/ci/nx-ci-consolidation.md. Workspace/tooling primer (pnpm config, Nx affected graph, local commands): docs/pnpm-nx-workspace.md. Read both first.

When to use

• Adding or changing a package's CI (prebuilds, cpp tests, integration, on-pr checks, benchmarks, on-merge publish).
• Onboarding a new package to the consolidated pipeline.
• Generalising a bespoke per-package workflow into a leaf.
• Editing nx-project-matrix or any *-nx.yml leaf.
• Debugging why a stage ran / didn't run for a package.

Mental model: config is data, the leaf is generic

The matrix action flattens every field under options.ci into each matrix row generically ({package, workdir, ...ci} + platform). So a leaf reads a field as ${{ matrix.<field> }} and a new field needs no action change — only the project.json (produce it) and the leaf step (consume it). Keep behaviour in data; touch a .yml only when a genuinely new step/shape is needed.

Hard rules

1. Config is read from the trusted default branch, never PR head. nx-project-matrix does git show <config-ref>:packages/<pkg>/project.json, and on pull_request_target config-ref = default_branch. A new package's project.json must land on the default branch before its CI runs. Never "fix" a pre-merge red by reading config from head.
2. Fork safety is non-negotiable. on-pr-nx.yml is pull_request_target (base context, secrets). Base = control surface, head = code-under-test. Every privileged job has fork-approval first in needs: and gates on authorize.outputs.allowed. Never add a privileged job without both. Leaves build/test github.event.pull_request.head.sha — only after the gates pass.
3. Mobile stays as main's. Do not consolidate integration-mobile-test-<pkg>.yml or add mobile to PRs beyond the existing asr/tts coload-smoke-mobile main-parity job. Never add run-mobile-addon-tests on PRs.
4. hasPrebuilds is derived, not declared — it is true iff build.options.ci exists. Don't add it by hand.
5. Overrides are validated. The action's overrides input can only set a field a package already declares — a PR cannot inject new CI behaviour. Keep it that way.
6. Merge-gated jobs go through qvac-merge-guard / validate-pr only. Never create a second required check. Use the qv-merge-guard-wire skill / docs/ci/MERGE-GUARD.md.
7. Never delete/skip/weaken a test. Fix the code or the config.

Recipe A — change an existing package's CI (data-only)

1. Edit packages/<pkg>/project.json → targets.<target>.options.ci. Adjust the existing field (e.g. add a platform row to test:cpp, flip includeVulkanSdk, change a perf-report pattern).
2. Nothing else if the field is already consumed by the leaf. Validate (below).

Recipe B — add a NEW options.ci field (data + one leaf step)

1. Add the field under the target's options.ci in the package(s) that need it. Others simply won't have it (matrix row omits it → ${{ matrix.<field> }} is empty).
2. Consume it in the leaf: reference ${{ matrix.<field> }} in the relevant step, or gate a step with if: ${{ matrix.<field> }}. For a whole flag-gated job, add a filtered sublist in the matrix job's filter step (jq select(.<field> == true)) and drive the job off fromJSON(needs.matrix.outputs.<field>list).
3. Do not touch nx-project-matrix — pass-through is generic.