docs(auto-merge-guide): expand Copilot auto-approve race-condition guide#59
Merged
Conversation
The existing "Auto-Approve Race Condition with Copilot Reviewer"
section covered the re-run fix but omitted diagnosis, prevention,
and a second observed symptom (empty reviewDecision, not just
REVIEW_REQUIRED). A concrete session hit this on a PR where 43
checks were green, auto-approve reported success, and the PR still
showed mergeStateStatus=BLOCKED with reviewDecision="". Nothing in
the skill pointed at the workflow-config root cause.
Changes:
- auto-merge-guide.md: mark the section as the canonical home for
this gotcha (project CLAUDE.md files should cross-reference it
instead of restating). Add:
- Second symptom: reviewDecision="" (empty string) observed
when Copilot is mid-review and required_approving_review_count
>= 1.
- Diagnosis block: how to extract the auto-approve job id and
grep its logs for the silent skip marker; how to query current
requested_reviewers to confirm Copilot has cleared.
- Expected post-fix state: mergeStateStatus=CLEAN,
reviewDecision=APPROVED.
- Why the rerun works, with cross-link to the existing "CI
Re-runs Replay the Same Commit" section so people don't rerun
the OLD failed run.
- Prevention patterns A/B/C (pull_request_review trigger, poll
with retry, pull_request_review-gated approval), plus an
anti-pattern warning against setting
required_approving_review_count to 0.
Updated the troubleshooting-table row to cover both symptom
variants and to link to the expanded section instead of "see below".
- SKILL.md: mention the Copilot green-CI race in the frontmatter
description, and update the "Merge Strategy Issues" quick line to
point at the canonical section.
- checkpoints.yaml: new mechanical check GH-33 that detects a
pr-quality.yml without a pull_request_review trigger (warning).
Follows the existing GH-24..GH-27 pattern of regex/command checks
against workflow files; no-ops if the workflow doesn't exist.
Observed on netresearch/t3x-nr-vault PR #116 during an auto-merge
session — the failure mode matches the CLAUDE.md learned-rule
"Auto-Approve Race Condition with Copilot Reviewer", which will now
cross-reference this file instead of duplicating it.
Signed-off-by: Sebastian Mendel <sebastian.mendel@netresearch.de>
Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
Signed-off-by: Sebastian Mendel <sebastian.mendel@netresearch.de>
Contributor
|
Warning You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again! |
Contributor
Dependency Review✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.Scanned FilesNone |
There was a problem hiding this comment.
Pull request overview
Expands documentation and project guidance around a GitHub Copilot reviewer / auto-approve race condition, and adds a repository checkpoint to detect workflows likely to hit it.
Changes:
- Expanded the “Auto-Approve Race Condition with Copilot Reviewer” section to include symptoms, diagnosis steps, remediation, and prevention options.
- Updated
SKILL.mdmetadata and quick guidance to reference the expanded canonical documentation. - Added checkpoint
GH-33to warn whenpr-quality.ymllacks apull_request_reviewtrigger.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
| skills/github-project/references/auto-merge-guide.md | Extends the race-condition guide (symptoms/diagnosis/fix/prevention) and updates the troubleshooting table. |
| skills/github-project/checkpoints.yaml | Adds GH-33 checkpoint to detect missing review-trigger coverage in pr-quality.yml. |
| skills/github-project/SKILL.md | Surfaces the race condition in the skill description and points to the canonical guide section. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Skill Validation requires SKILL.md <= 500 words. After the previous commit's additions (Copilot-review race diagnosis) the file grew to 530 words. Tighten: - Description: drop 'Dependabot/Renovate' redundancy (already implied by 'auto-merge'), shorten parenthetical - Merge Strategy Issues: replace the inline list with a single pointer at references/auto-merge-guide.md — the details live there anyway, and this removes ~30 words Final: 492 words. Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
- Scope RUN_ID lookup by PR head SHA in diagnosis and rerun snippets so the examples don't pick runs from unrelated PRs/branches. - Pipe JOB_ID extraction to head -1 to guarantee a single id. - Read job logs via 'gh run view --log' instead of 'gh api .../logs', which returns a zipped artifact that can't be grepped directly. - Use POSIX-portable [[:space:]] instead of \s in the checkpoints.yaml grep, since ERE \s is a GNU extension. Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
Merged
CybotTM
added a commit
that referenced
this pull request
May 15, 2026
## Release v2.14.0 Minor release. `.claude-plugin/plugin.json` and `skills/github-project/SKILL.md` frontmatter `metadata.version` were already synced to `2.14.0` on `main` via [#74](#74) — this PR is the empty release marker that closes the v2.13.1 → v2.14.0 window and triggers the signed-tag release. ### Highlights since v2.13.1 - **`agentic-workflows` reference** documenting `gh-aw` and `awf` workflow-as-prompt tooling for autonomous GitHub Actions — new patterns for running AI agents on PRs/issues without bespoke wiring ([#75](#75)). - **AI reviewer pushback patterns** — handling Copilot/Sourcery review comments that disagree with the codebase intent, including when to defer and when to push back ([#66](#66), [#74](#74)). - **PR-merge / branch-protection / CodeQL gotchas** documented, plus auto-detection of allowed merge strategy in the `--delete-branch` snippet so the recipe doesn't break on repos with merge-commit-only policies ([#69](#69), [#71](#71), [#72](#72)). - **GraphQL `Repository.mergeQueue`** for queue detection — replaces a brittle REST probe ([#70](#70)). - **Assessment checkpoints overhaul**: new GH-34/GH-35/GH-36, follow_uses delegation for CodeQL/Scorecard, org_provides for community-health files, broader licence/Dependabot/workflow targets, plus reusable-workflow-pitfalls reference. Multiple false-positive findings demoted to `info` to reduce assessment noise ([#56](#56), [#57](#57), [#58](#58), [#59](#59), [#60](#60), [#61](#61), [#62](#62), [#63](#63), [#64](#64), [#65](#65), [#73](#73)). - **npm distribution** — the skill now also ships via `@netresearch/agent-skill-coordinator` ([#54](#54), [#55](#55)). - **Release pipeline hardening** — dropped the deprecated `with: bump:` block + `workflow_dispatch.bump` input so releases happen exclusively via locally-signed tags, plus SLSA-provenance permissions on the caller ([#52](#52), [#53](#53)). ### Release plan After merge: tag main with a signed annotated tag, push, the `skill-repo-skill` reusable workflow publishes archives + SHA256SUMS with cosign + SLSA attestation, then narrative notes get applied via `gh release edit ... --notes-file`.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Expands the existing Auto-Approve Race Condition with Copilot Reviewer section in
references/auto-merge-guide.mdso it covers the full diagnose-fix-prevent cycle instead of just the re-run workaround. Marks it as the canonical home for this gotcha so project-levelCLAUDE.mdentries can link here instead of duplicating the details.Why
A concrete session hit this on netresearch/t3x-nr-vault#116:
SUCCESSpr-quality / Auto-Approve (Solo Maintainer)job reported successgithub-actions[bot]had approved the PR (from a previous push)CHANGES_REQUESTEDmergeStateStatus: BLOCKED,reviewDecision: ""(empty string — notREVIEW_REQUIRED)The skill covered the re-run fix but didn't mention:
reviewDecisionsymptom variant (distinct fromREVIEW_REQUIRED)So the user's project-level
CLAUDE.mdcarried the full write-up (Auto-Approve Race Condition with Copilot Reviewer) — per the learned-rule "Skills are team memory", that content belongs here.Changes
references/auto-merge-guide.md— expand the race-condition section:reviewDecision: ""requested_reviewers)pull_request_reviewtrigger / poll-with-retry / gate onpull_request_review)required_approving_review_count: 0CI Re-runs Replay the Same Commitso people don't rerun the old failed runSKILL.md— surface "Copilot reviewer race conditions" in the frontmatterdescriptionand update the Merge Strategy Issues quick line to point at the canonical sectioncheckpoints.yaml— newGH-33(severitywarning): detectspr-quality.ymlthat lacks apull_request_reviewtrigger. No-ops when the workflow doesn't exist. Follows the existingGH-24..GH-27pattern of command/regex checks against workflow files.Test plan
yamllint skills/github-project/checkpoints.yamlclean#ci-re-runs-replay-the-same-commit,../assets/pr-quality.yml.template,#auto-approve-race-condition-with-copilot-reviewer)Signed-off-by:matches author (sebastian.mendel@netresearch.de)