NO-JIRA: Fix parallel CAPI verification race

CONTRIBUTING.md

@@ -34,7 +34,7 @@ The following guidelines will help ensure a smooth contribution process for both
 
 This project uses [Prow](https://docs.ci.openshift.org/) and [GitHub Actions](https://github.com/openshift/hypershift/actions) for CI. Lightweight checks (linting, unit tests, verification) run automatically on pushes and pull requests. E2E tests that consume real cloud infrastructure only run after a reviewer grants `/lgtm`, to avoid unnecessary resource usage on work-in-progress PRs.
 
-**Adding CI targets:** When you add a new `make` target to `verify-parallel` or any other CI-facing Makefile target, you must also add it to the corresponding GitHub Actions workflow (e.g., `.github/workflows/verify-reusable.yaml` for verify targets, or as a new "reusable" target). GitHub Actions provide fast feedback on PRs; Prow runs heavier e2e tests. Targets that only exist in the Makefile without a matching GH Actions step will not run in CI.
+**Adding CI targets:** Ensure each new check is reachable from the corresponding GitHub Actions workflow, either through a Makefile entrypoint it already invokes or through a workflow step. For example, `.github/workflows/verify-reusable.yaml` runs `make verify-ci`, which delegates to `verify-serial-targets`; changing that group's contents does not require a separate workflow step. Adding a target only to `verify-parallel-targets` does not automatically include it in that workflow. GitHub Actions provide fast feedback on PRs; Prow runs heavier e2e tests.
 
 See hack/github-actions-runner/README.md for details.
 

DEVELOPMENT.md

@@ -237,7 +237,7 @@ make verify-capi-decoupling   # Check the invariants below without a full CI run
 
 Because each provider is a separate module reached through `replace`, `go build ./...` in the root module compiles only the provider subpackages something imports — a broken `exp/api` package stays invisible until CRD generation. It also means the localized `capicore` types and the upstream CAPI types they were copied from are **distinct Go types**: code merged from upstream that names `clusterv1beta1` or `capiv1` where a file already uses `capicore` will not compile, and the error does not say why.
 
-`make verify-capi-decoupling` (`hack/verify-capi-decoupling.sh`) checks this in seconds: no provider module may require or import `sigs.k8s.io/cluster-api`, every subpackage of every provider module must build, and the packages that consume `capicore` types must vet. It runs in `verify-parallel` and `verify-ci`; run it locally after **any merge or rebase onto main that touched provider types**, which is where the alias mismatch usually arrives from.
+`make verify-capi-decoupling` (`hack/verify-capi-decoupling.sh`) checks this in seconds: no provider module may require or import `sigs.k8s.io/cluster-api`, every subpackage of every provider module must build, and the packages that consume `capicore` types must vet. It runs after `verify-capi-sync` in `verify-serial-targets`, invoked by `verify` and `verify-ci`; run it locally after **any merge or rebase onto main that touched provider types**, which is where the alias mismatch usually arrives from.
 
 The sync process (`hack/capi-sync-provider.sh`) for each provider:
 1. Downloads the upstream module into the Go module cache via `go mod download`

Makefile

@@ -182,16 +182,28 @@ verify-crd-schema: $(CRD_SCHEMA_CHECK) ## Verify CRD schemas for breaking change
 		--crd-dir=cmd/install/assets/crds/hypershift-operator \
 		--crd-dir=karpenter-operator/controllers/karpenter/assets/zz_generated.crd-manifests
 
-.PHONY: verify-parallel
-verify-parallel: verify-codespell verify-codecov verify-api-deps verify-crd-schema verify-capi-sync verify-capi-decoupling lint cpo-container-sync run-gitlint verify-docs-nav verify-tekton-pipeline-pairs
+# Targets that conflict, such as deleting or mutating a directory another target
+# reads, must move to verify-serial-targets instead of running in parallel here.
+.PHONY: verify-parallel-targets
+verify-parallel-targets: verify-codespell verify-codecov verify-api-deps verify-crd-schema lint cpo-container-sync run-gitlint verify-docs-nav verify-tekton-pipeline-pairs
+
+# Run target checks sequentially after preparation.
+.PHONY: verify-serial-targets
+verify-serial-targets:
+	# Sync regenerates provider sources that decoupling builds and lint reads.
+	$(MAKE) verify-capi-sync
+	$(MAKE) verify-capi-decoupling
 
 .PHONY: verify-ci
-verify-ci: generate update staticcheck fmt vet lint verify-api-deps verify-crd-schema verify-capi-decoupling verify-docs-nav verify-tekton-pipeline-pairs ## Run the same checks as the GHA verify workflow.
+verify-ci: generate update staticcheck fmt vet verify-api-deps verify-crd-schema verify-docs-nav verify-tekton-pipeline-pairs ## Run the same checks as the GHA verify workflow.
+	$(MAKE) verify-serial-targets
+	$(MAKE) lint
 	$(MAKE) verify-git-clean
 
 .PHONY: verify
 verify: generate update staticcheck fmt vet
-	$(MAKE) -j verify-parallel
+	$(MAKE) verify-serial-targets
+	$(MAKE) -j verify-parallel-targets
 	$(MAKE) verify-git-clean
 
 .PHONY: verify-quick

hack/capi-sync-provider.sh

@@ -157,7 +157,7 @@ while read -r pkg; do
         [[ -n "$prefix" ]] || continue
         allow_args+=(--allow "$prefix")
     done < <(allow_prefixes "$PROVIDER:$sub")
-    copy_types "$SRC/$sub" "$DST_DIR/$sub" "${allow_args[@]}"
+    copy_types "$SRC/$sub" "$DST_DIR/$sub" ${allow_args[@]+"${allow_args[@]}"}
 done < <(provider_packages)
 
 while read -r glob; do