Add field-tested PR/CI/merge-gate gotchas#94
Conversation
github-actions
Bot
added
documentation
Dependency Review✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.Scanned FilesNone |
![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 several reference documentation files (gh-cli-reference.md, merge-strategy.md, pr-commit-cleanup.md, and reusable-workflow-pitfalls.md) with comprehensive troubleshooting patterns and best practices for GitHub CLI, PR merging, and reusable workflows. The review feedback suggests improving the robustness of the documented commands by parameterizing GraphQL queries and utilizing null-safe jq expressions with optional chaining and default fallbacks.
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.
Promote battle-tested GitHub PR/CI/merge-gate lessons into the shared reference docs: - gh-cli-reference.md: native CI watcher over hand-rolled poll loops; gh run rerun re-runs old state (only for genuine flakes); rapid gh api 401 + while-read trap; adding images via fork-branch raw URLs. - merge-strategy.md: diagnose BLOCKED before naming a cause; never merge over an in-flight review; gh pr merge GraphQL false "policy prohibits" vs REST fallback; merge-method ruleset deadlock; Copilot-quota ruleset admin-merge; SonarCloud new-code re-attribution on refactors. - pr-commit-cleanup.md: never reset a PR head ref to its base (auto-close). - reusable-workflow-pitfalls.md: fresh-run recipes for scheduled/non-PR repos and moving-tag caveat; zero-jobs startup_failure diagnosis. Signed-off-by: Sebastian Mendel <github@sebastianmendel.de>
CybotTM
force-pushed
the
retro-promote-pr-ci-gotchas
branch
from
b18c3b8 to
703d24e
Compare
Address review feedback: use a parameterized GraphQL query with -f/-F flags and null-safe jq in the merge-strategy reviewThreads check, and add a null-safe fallback to the default_workflow_permissions query. Signed-off-by: Sebastian Mendel <github@sebastianmendel.de>
|
Why
These are battle-tested GitHub PR/CI/merge-gate gotchas accumulated from repeated field use across many repos. They were living in private project memory; they belong in the shared skill so every agent run benefits instead of re-discovering each trap. Each lesson is generalized — host/ticket/user specifics stripped, only the transferable rule kept.
What
Integrated 14 lessons into the most fitting existing reference (no new files, SKILL.md untouched):
gh-cli-reference.mdgh pr checks --watch/gh run watch) instead of hand-rolled poll loops — documents the three recurring watcher bugs (empty-stringconclusion, premature 0-pending snapshot, wrongcreatedAtcutoff).gh run rerunre-runs the OLD pinned state (merge-commit base) — only correct for genuine infra flakes (registry pull timeouts, Sigstore 409s, codecov partials).gh apicalls intermittently 401; thewhile readconsumes-error-text trap.raw.githubusercontent.comURL (no browser needed).merge-strategy.mdBLOCKEDbefore naming a cause;reviewThreadsis GraphQL-only, not agh pr view --jsonfield.reviewRequests: []is not "all clear").gh pr mergefalse "base branch policy prohibits the merge" → RESTPUT .../mergefallback (only after the gate is truly verified).allowed_merge_methods∩ repo flags = empty;--admincan't bypass).pr-commit-cleanup.mdreusable-workflow-pitfalls.md@mainreusable; moving-tag caveat (registry immutability).startup_failurediagnosis (dead reusable reference vs. permission mismatch).Source memory → reference
All four files pass markdownlint-cli2 and the repo pre-commit suite.