docs(reusable-workflows): make pitfall #6 fire when editing a consumer workflow#125
Conversation
…r workflow Pitfall #6 already states that a CI gap belongs upstream in the shared workflow rather than in the consumer. It did not fire in a session that added a local acceptance-test job -- with its own checkout and PHP setup -- to two consumer repos, and the maintainer had to correct it twice. Two reasons, both addressed here. The skill was never loaded: the description said "authoring reusable workflows", which reads as authoring the shared workflow, not as editing a consumer's .github/workflows. The description and the When to Use list now name that case, kept within the 500-word cap by folding the duplicated branch-protection note into its list entry. And the pitfall stated the principle without a test for it. It now gives the consumer-side tell -- every job in a consumer is a `uses:` of a shared workflow, so a job with its own `steps:` or any non-org action is the smell, with a grep to check it -- plus the mechanics of the upstream alternative: an additive input defaulting to off, pins copied from a neighbouring job, a graceful skip for consumers that are not ready, and a warning against smuggling an extra suite through a command-override input, which silently drops the instrumented default such as the coverage upload. Signed-off-by: Sebastian Mendel <github@sebastianmendel.de>
Dependency Review✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.Scanned FilesNone |
github-actions
Bot
added
documentation
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the GitHub project skill documentation, clarifying when to use the skill and adding detailed guidance on avoiding reusable workflow pitfalls, specifically regarding consumer-side workflow smells and how to safely extend shared workflows. The review feedback suggests keeping the push requirement before running the branch protection script to avoid failures on empty repositories, using case-insensitive matching when filtering organization names in workflow paths, and comparing against the base branch in the git diff command to ensure all changes are properly verified.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
Restores "+ push" to the bootstrap entry: init-branch-protection.sh exits 4
on an empty repo ("default branch ref does not yet exist"), so the push is a
precondition, not narrative. Compressing that line to stay under the word cap
had dropped it. SKILL.md is at 499 words.
Makes the consumer-side grep case-insensitive, since an org can appear with
different casing in a uses: path, and compares against the base branch rather
than the working tree when checking that the upstream change is additive --
git diff -U0 alone reports nothing once the change is staged or committed,
which would read as a pass.
Signed-off-by: Sebastian Mendel <github@sebastianmendel.de>
|
Came from
/retroon a session working two TYPO3 extension PRs (netresearch/t3x-nr-image-optimize#115 / #116).This is a C4 finding — the guidance existed and did not hold. Pitfall #6, added by an earlier
/retroin #82, already says a CI gap belongs upstream in the shared workflow rather than in the consumer. I nonetheless added a localacceptancejob with its ownactions/checkoutandshivammathur/setup-phpto both consumer repos, and the maintainer had to correct it — then had to correct it a second time when I asked whether to SHA-pin a third-party action seconds after being told we don't use them.Why it didn't fire
The skill was never loaded. The
descriptionsaid "authoring reusable workflows", which reads as authoring the shared workflow — not as editing a consumer's.github/workflows. That is the case I was in, and no trigger word covered it.The pitfall stated a principle without a test for it. "Ask whether the shared repo owns that concern" needs judgement at exactly the moment you have already decided to write the job. A mechanical tell is easier to obey.
Change
SKILL.md—descriptioncovers consuming reusable workflows and editing a repo's own.github/workflows; aWhen to Useentry points at pitfall feat: add Go project CI checklist and related skills section #6. The file is at the 500-word limit, so this is paid for by folding the duplicated branch-protection note (it appeared both as a list item and as a standalone blockquote) into its list entry. 497 words after the change, verified withwc -w.references/reusable-workflow-pitfalls.md— pitfall feat: add Go project CI checklist and related skills section #6 gains:uses:of a shared workflow, so a job with its ownsteps:, or any non-org action, is the smell; with a grep that checks it. Notes that SHA-pinning such an action does not make it compliant.false, purely-additive diff check, pins copied verbatim from a neighbouring job, graceful skip for consumers without the underlying script, then a one-line flip in the consumer.unit-test-command-style override inputs, which replace the job's instrumented default and silently drop what it did (in that session, the Codecov upload).The upstream path described here is the one that ended up being taken: netresearch/typo3-ci-workflows#136 added a
run-acceptance-testsinput defaulting tofalse(113 insertions, 0 deletions), and both consumers then enabled it with one line.Test plan
markdownlint-cli2, skill-structure validation and version parity — passedwc -w skills/github-project/SKILL.md→ 497 (cap 500)