feat(checkpoints): add GH-34/35/36 + reusable-workflow-pitfalls reference

[CybotTM]

Motivation

A recent multi-day session shipping reusable GHA workflows in netresearch/typo3-ci-workflows and a consumer wiring in netresearch/t3x-rte_ckeditor_image hit three avoidable issues that this PR makes catchable mechanically:

1. uses: …/preflight-gate@main self-reference inside reusable workflows broke SHA-pinned consumers. Composite-action references inside reusable workflows are resolved at the consumer's runner under the consumer's allow-list policy. PR #82 had to be followed by PR #83 (inline the bash, drop the composite action) once a SHA-pinned consumer rejected @main. feat: add GraphQL --input pattern for special characters #34 catches this.
2. Five preflight jobs added without step-security/harden-runner. Caught only after Copilot flagged five separate workflow files in the same PR. The convention is consistent across the repo: every job's first step is the pinned harden-runner. Add GitHub Actions upgrade guide with breaking changes reference #35 catches this mechanically.
3. PR review feedback declared "addressed" with two threads still unresolved. Twice in the session a "PR is ready" claim was made without verifying that all review threads were marked resolved — the user found the discrepancy when the PR stayed BLOCKED. feat: add fork workflow pattern and archived actions docs #36 is the process reminder.

A fourth, related observation made it into the new reference doc: gh run rerun caches uses: …@ref resolution from the original run trigger time, so re-running after an upstream fix lands picks up nothing — the workflow_ref has to change.

Changes

Three new checkpoints

# === COMPOSITE-ACTION SHA PINNING INSIDE WORKFLOWS ===
# Reusable-workflow refs like `uses: org/repo/.github/workflows/foo.yml@main`
# are exempt (see references/reusable-workflow-security.md — internal `@main`
# is allowed for full reusable workflows). Composite-action refs like
# `uses: org/repo/.github/actions/foo@main` are NOT exempt: they are resolved
# at the *consumer's* runner under the consumer's allow-list policy. A
# consumer that enforces "all actions must be SHA-pinned" will reject a
# reusable workflow that internally references a composite action by branch
# or tag, even though the workflow file itself is unchanged. SHA-pin
# composite-action refs to avoid breaking SHA-pinned consumers.
# PCRE negative lookahead matches refs that are NOT a 40-char hex SHA.
- id: GH-34
  type: regex_not
  target: ".github/workflows/*.{yml,yaml}"
  pattern: 'uses:\s+["'"'"']?[A-Za-z0-9._-]+/[A-Za-z0-9._-]+/\.github/actions/[^@]+@(?![0-9a-f]{40}\b)'
  severity: error

# === HARDEN-RUNNER FIRST-STEP CHECK ===
# Mechanical YAML-AST check via python yaml.safe_load (a regex-only check
# cannot reliably reason about "first step of each job" across multi-line
# YAML). Skipped if PyYAML is unavailable. Jobs that are pure
# reusable-workflow callers (job-level `uses:` instead of `steps:`) are
# exempt — they have no runner steps to harden.
- id: GH-35
  type: command
  target: |
    command -v python3 >/dev/null 2>&1 || exit 0
    # ... yaml.safe_load + first-step check, exits 1 if any job's
    # first non-uses step isn't step-security/harden-runner
  severity: warning

# === PR REVIEW COMPLETENESS PROCESS CHECK ===
- id: GH-36
  domain: pr-process
  prompt: |
    Before declaring PR review feedback addressed:
    1. Query unresolved threads via GraphQL (reviewThreads → isResolved=false)
    2. Count must be exactly zero.
    3. If non-zero, list each thread with first comment body + path/line.
    Common failure: addressing only top-of-discussion threads, missing
    inline-code or earlier-reviewer threads.
  severity: info

(See the diff for the full embedded python script in GH-35 and the full prompt in GH-36.)

New reference doc — references/reusable-workflow-pitfalls.md

This complements rather than overlaps references/reusable-workflow-security.md:

• reusable-workflow-security.md — supply-chain trust, SHA-pinning external actions, transitive-dependency risks, audit checklist for adopting third-party workflows.
• reusable-workflow-pitfalls.md (new) — operational/structural traps when authoring internal reusable workflows:
  1. ./ does NOT resolve to the reusable workflow's repo (linked to GitHub docs)
  2. Composite-action SHA-pinning rule (the rule feat: add GraphQL --input pattern for special characters #34 enforces)
  3. gh run rerun caches @ref resolution at original trigger time
  4. Permissions ceiling — caller's job-level permissions clamp the token

SKILL.md

• description: broadened to activate on reusable-workflow, composite-action, and harden-runner authoring tasks (329 chars total, under the ~350 ceiling).
• References table gains rows for both reusable-workflow-security.md (previously not listed) and the new reusable-workflow-pitfalls.md.

Self-test

• python3 -c 'import yaml; yaml.safe_load(open("checkpoints.yaml"))' — parses cleanly.
• yamllint -c .yamllint.yml skills/github-project/checkpoints.yaml — no warnings.
• feat: add GraphQL --input pattern for special characters #34 PCRE pattern smoke-tested against a synthetic mix of composite-action / reusable-workflow / external-action refs at SHA / branch / tag refs — only the offending lines match.
• Add GitHub Actions upgrade guide with breaking changes reference #35 embedded python run against this repo's own .github/workflows/*.yml exits 0 (all jobs already start with step-security/harden-runner).
• feat: add GraphQL --input pattern for special characters #34 grep over this repo's own .github/workflows/*.yml — clean.

Test plan

• CI checks pass on this PR
• Run the automated-assessment skill against a known-bad repo (composite action @main ref) and confirm feat: add GraphQL --input pattern for special characters #34 fires
• Run against a workflow with a job whose first step isn't harden-runner and confirm Add GitHub Actions upgrade guide with breaking changes reference #35 fires

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[gemini-code-assist]

Code Review

This pull request updates the github-project skill by expanding its description and adding new checkpoints for GitHub Actions security and process management. Specifically, it introduces checks for SHA-pinning composite actions (GH-34), ensuring harden-runner is the first step in workflow jobs (GH-35), and verifying that all PR review threads are resolved via GraphQL (GH-36). Additionally, a new reference document, reusable-workflow-pitfalls.md, has been added to provide guidance on common issues with reusable workflows and composite actions. I have no feedback to provide.

[Copilot]

Pull request overview

Adds new mechanical/process checkpoints and supporting documentation to make common reusable-workflow authoring pitfalls and PR-review completeness issues detectable and repeatable within the github-project skill.

Changes:

• Add three new checkpoints: GH-34 (composite-action SHA pinning), GH-35 (harden-runner first-step enforcement), GH-36 (verify all PR review threads resolved via GraphQL).
• Add a new reference doc: references/reusable-workflow-pitfalls.md.
• Update SKILL.md description and references table to include reusable-workflow content.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
skills/github-project/checkpoints.yaml	Adds GH-34/35/36 checkpoint definitions (regex + embedded Python + process prompt).
skills/github-project/references/reusable-workflow-pitfalls.md	New reference documenting reusable-workflow authoring pitfalls (local action resolution, SHA pinning, rerun ref caching, permissions ceiling).
skills/github-project/SKILL.md	Expands activation description and links in new reusable-workflow reference docs.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud