[imaqsood]

Summary

Companion to puppetlabs/pdk-templates#680. Updates the fork-PR CI doc and the example caller to the safer gate it renders:

• Example ci.yml: fork acceptance runs only on the labeled event for allowed-for-ci, not whenever the label is present. A new Fork_CI_Label_Guard job calls fork_ci_label_guard.yml on synchronize/closed. Concurrency is keyed on the event and the PR number. Same-repo PRs keep their existing labeled/reopened acceptance behaviour.
• docs/how-to/fork-pr-ci.md: step 5 and "How it works" describe the guard as a ci.yml job. The "do not add synchronize" rule becomes "gate on the labeling event, never on label presence", plus a note on per-PR concurrency.
• Example fork_ci_label_guard.yml: a note says it's only needed when the caller's ci.yml doesn't run the guard. Don't use both.
• CLAUDE.md: the fork-PR security model paragraph is updated to match.

No reusable workflow under .github/workflows/ changes.

Additional Context

• Root cause: the "don't add synchronize" rule exists because a synchronize payload still carries allowed-for-ci until the guard strips it, so contains(labels) would race the guard. The same presence check also lets a reopened event run acceptance if the label survived. And keeping the guard in a separate file means modules can miss it: pdk-templates renders ci.yml for modules that opt in, but fork_ci_label_guard.yml is unmanaged by default (pdk-templates#670). (MODULES-11999) pdk update to pdk-templates main (8ca954f) puppetlabs-facter_task#252 shipped the trigger without the guard, which Copilot review flagged.
• Thought process: gating on the labeling event closes both holes. synchronize and closed can then only run the guard, never acceptance, so ci.yml can carry the guard itself and the two can't drift apart. Acceptance still checks out the head SHA from the labeled payload.
• Not covered: module_acceptance.yml's setup_matrix checks out the fork head and runs bundle install with PUPPET_FORGE_TOKEN set before approval_gate, so the puppetcore-fork environment approval doesn't cover that job. The fork's Gemfile is evaluated with the token before anyone approves. That's worth its own change: run the gate first, or give setup_matrix no token for fork PRs.

Related Issues (if any)

MODULES-12062 (epic MODULES-11997), puppetlabs/pdk-templates#680. Follows CAT-2632 / CAT-2662.

Checklist

• 🟢 Spec tests.
• 🟢 Acceptance tests.
• Manually verified: yamllint -c .yamllint .github/ plus the two changed example files pass. actionlint passes on both examples. (example/module/labeller.yml already fails yamllint on main; it's untouched here.)

🤖 Generated with Claude Code

[imaqsood]

Closing: the fix moved to a smaller change in puppetlabs/pdk-templates#680 that stays within the existing fork-CI design, so the doc and example don't need to change.