diff --git a/AGENT.md b/AGENT.md index 995a21cc3..7edd26054 100644 --- a/AGENT.md +++ b/AGENT.md @@ -95,28 +95,54 @@ and **Copilot**. ## Setup -### 1. Create a fine-grained PAT - -Go to . Settings: - -- **Resource owner:** `don-petry` -- **Repository access:** "All repositories" (or pick the ones you want the - agent to act on). -- **Repository permissions:** - - Contents: **Read** - - Issues: **Read and write** (needed to create labels and add `needs-human-review`) - - Metadata: **Read** (auto) - - Pull requests: **Read and write** -- **Expiration:** as long as you're comfortable with. Set a calendar reminder - to rotate. - -Save the token, then add it as a repo secret on `don-petry/self`: +### Reviewer identity + +The agent posts PR reviews and approvals using the `GH_PAT` secret. This +token **must belong to a different GitHub account than the PR author** — +GitHub blocks self-approval (a user cannot approve their own PR). If the +same account both opens PRs (via Claude automation) and tries to approve +them, every approval will silently fail. + +The recommended pattern: create a dedicated **reviewer bot account** +(e.g. `petry-review-bot`) whose token is stored as `GH_PAT`. PRs are +authored by `don-petry`; the bot approves them. + +### 1. Create the reviewer bot account + +1. Sign out of GitHub (or use a private browser window). +2. Go to and create a new account. + - **Username:** e.g. `petry-review-bot` + - **Email:** a dedicated alias works well (e.g. `you+petry-review-bot@gmail.com`) +3. Verify the email address. +4. Sign back in as `don-petry`. +5. Go to **github.com/organizations/petry-projects/settings/members** → + **Invite member** → enter `petry-review-bot` → Role: **Member**. +6. Accept the invite from the bot account. + +### 2. Create a classic PAT for the bot + +A classic PAT is required — fine-grained PATs cannot satisfy the GitHub +rulesets bypass that org-admin approval requires. + +1. Sign in as `petry-review-bot`. +2. Go to **Settings → Developer settings → Personal access tokens → + Tokens (classic)** → **Generate new token (classic)**. +3. Settings: + - **Note:** `pr-review-agent` + - **Expiration:** 1 year (set a calendar reminder to rotate) + - **Scopes:** ✅ `repo` +4. Generate and copy the token immediately. +5. Sign back in as `don-petry` and store the token: ``` gh secret set GH_PAT --repo don-petry/self ``` -### 2. Add your LLM engine auth token +> **Branch protection / rulesets:** add `petry-review-bot` as an allowed +> approver on each protected repo. In the repo ruleset or branch protection +> settings, ensure the bot is not excluded from the reviewer pool. + +### 3. Add your LLM engine auth token #### Claude engine (default) @@ -140,7 +166,7 @@ Create a GitHub PAT with Copilot scope. Store as a repo secret: gh secret set COPILOT_GITHUB_TOKEN --repo don-petry/self ``` -### 3. Choose your engine +### 4. Choose your engine ``` # Use Copilot (GPT models): @@ -150,7 +176,7 @@ gh variable set REVIEW_ENGINE --body copilot --repo don-petry/self gh variable set REVIEW_ENGINE --body claude --repo don-petry/self ``` -### 4. Test with a dry run +### 5. Test with a dry run ``` gh workflow run pr-review.yml --repo don-petry/self -f dry_run=true diff --git a/prompts/cascade-action.md b/prompts/cascade-action.md index bb926faab..a620c5e91 100644 --- a/prompts/cascade-action.md +++ b/prompts/cascade-action.md @@ -65,6 +65,17 @@ _Reviewed by the don-petry PR-review cascade ($ENGINE_LABEL). Reply with `@don-p 1. `gh pr review "$PR_URL" --approve --body "$BODY"` 2. Rebase if `mergeStateStatus` is `BEHIND`: `gh api -X PUT "repos///pulls//update-branch" -f expected_head_sha="$PR_HEAD_SHA"` (swallow errors) + Then poll until the branch is no longer `BEHIND` (up to 30 s, 5 s interval): + ``` + REBASE_STATUS="BEHIND" + for i in 1 2 3 4 5 6; do + REBASE_STATUS=$(gh pr view "$PR_URL" --json mergeStateStatus --jq '.mergeStateStatus') + [ "$REBASE_STATUS" != "BEHIND" ] && break + sleep 5 + done + ``` + If `REBASE_STATUS` is still `BEHIND` after the poll, **skip steps 3 and 4** — + the next review cycle will retry once the branch has caught up. 3. Auto-merge: `gh pr merge "$PR_URL" --auto --squash` (swallow errors) 4. Remove `needs-human-review` label if present (swallow errors) - If `decision` is `escalate`: diff --git a/prompts/single-review.md b/prompts/single-review.md index 4faf757b3..d2746191e 100644 --- a/prompts/single-review.md +++ b/prompts/single-review.md @@ -133,6 +133,17 @@ Then act: 1. `gh pr review "$PR_URL" --approve --body "$BODY"` 2. Rebase if `mergeStateStatus` is `BEHIND`: `gh api -X PUT "repos///pulls//update-branch" -f expected_head_sha="$PR_HEAD_SHA"` (swallow errors) + Then poll until the branch is no longer `BEHIND` (up to 30 s, 5 s interval): + ``` + REBASE_STATUS="BEHIND" + for i in 1 2 3 4 5 6; do + REBASE_STATUS=$(gh pr view "$PR_URL" --json mergeStateStatus --jq '.mergeStateStatus') + [ "$REBASE_STATUS" != "BEHIND" ] && break + sleep 5 + done + ``` + If `REBASE_STATUS` is still `BEHIND` after the poll, **skip steps 3 and 4** — + the next review cycle will retry once the branch has caught up. 3. Enable auto-merge: `gh pr merge "$PR_URL" --auto --squash` (swallow errors) 4. Remove `needs-human-review` label if present (swallow errors) - If escalating: diff --git a/prompts/synthesize.md b/prompts/synthesize.md index 1a7f76bf7..9b5d750d0 100644 --- a/prompts/synthesize.md +++ b/prompts/synthesize.md @@ -66,6 +66,17 @@ and (if `$DRY_RUN` is `false`) post a PR review. is `BEHIND` (base branch has advanced), update the PR branch: `gh api -X PUT "repos///pulls//update-branch" -f expected_head_sha="$PR_HEAD_SHA"` Swallow errors (conflicts will be caught on next cycle). + Then poll until the branch is no longer `BEHIND` (up to 30 s, 5 s interval): + ``` + REBASE_STATUS="BEHIND" + for i in 1 2 3 4 5 6; do + REBASE_STATUS=$(gh pr view "$PR_URL" --json mergeStateStatus --jq '.mergeStateStatus') + [ "$REBASE_STATUS" != "BEHIND" ] && break + sleep 5 + done + ``` + If `REBASE_STATUS` is still `BEHIND` after the poll, **skip steps 2 and 3** — + the next review cycle will retry once the branch has caught up. 2. **Enable auto-merge**: `gh pr merge "$PR_URL" --auto --squash` This tells GitHub to merge the PR once all required checks pass. Swallow errors if auto-merge is already enabled or not allowed. diff --git a/prompts/triage.md b/prompts/triage.md index 115bfc967..6ce0a9a3d 100644 --- a/prompts/triage.md +++ b/prompts/triage.md @@ -27,15 +27,14 @@ Output `"escalate": false` (approve) if ALL of these are true: - Database migrations or schema (`migrations/`, `schema.*`, `*.sql`, Prisma, Alembic) - GitHub Actions workflows that handle secrets or use `pull_request_target` - Files matching: `**/auth/**`, `**/*secret*`, `**/*credential*`, `**/*crypto*` -2. No CI checks are failing (look at `statusCheckRollup` in metadata). -3. No unresolved review threads requesting changes. -4. The diff does not contain obvious security anti-patterns: +2. No unresolved review threads requesting changes. +3. The diff does not contain obvious security anti-patterns: - SQL string concatenation, `eval`/`exec` on dynamic input, `shell=True` with user input, hardcoded secrets/passwords, disabled TLS verification, broad `except:` swallowing, `dangerouslySetInnerHTML`, etc. -5. If there's a linked issue, the diff appears to address it (use your judgment). -6. The PR is well-structured (clear title, reasonable scope). -7. If `$PRIOR_REVIEW_BODY` is non-empty: the new commits appear to resolve +4. If there's a linked issue, the diff appears to address it (use your judgment). +5. The PR is well-structured (clear title, reasonable scope). +6. If `$PRIOR_REVIEW_BODY` is non-empty: the new commits appear to resolve the findings from the prior review. Output `"escalate": true` if ANY of those checks fail. When in doubt, escalate. diff --git a/scripts/list-prs.sh b/scripts/list-prs.sh index 946f5a3d4..8605e78c7 100755 --- a/scripts/list-prs.sh +++ b/scripts/list-prs.sh @@ -5,10 +5,14 @@ # 1. PRs authored by @me across all repos (self-review). # 2. PRs where @me is a requested reviewer across all repos. # -# Filters out PRs that have already been reviewed (marked with -# in comments). +# Filters: +# --draft=false — skip work-in-progress PRs +# --checks passing — only include PRs where all CI checks are green; +# failing or pending CI PRs are excluded here so they +# never consume a review slot. review-one-pr.sh also +# enforces this per-PR as a second layer of defence. # -# Output: one PR URL per line on stdout. Drafts and already-reviewed PRs are excluded. +# Output: one PR URL per line on stdout. set -euo pipefail @@ -16,6 +20,7 @@ authored=$(gh search prs \ --state open \ --author "@me" \ --draft=false \ + --checks passing \ --limit 100 \ --json url \ --jq '.[].url') @@ -24,6 +29,7 @@ review_requested=$(gh search prs \ --state open \ --review-requested "@me" \ --draft=false \ + --checks passing \ --limit 100 \ --json url \ --jq '.[].url') diff --git a/scripts/review-one-pr.sh b/scripts/review-one-pr.sh index 15d8e82d1..5b4342d9c 100755 --- a/scripts/review-one-pr.sh +++ b/scripts/review-one-pr.sh @@ -30,11 +30,50 @@ export PR_URL echo "==> $PR_URL" -# 1. Current head SHA -PR_HEAD_SHA=$(gh pr view "$PR_URL" --json headRefOid --jq '.headRefOid') +# 1. Current head SHA + CI gate — single API call for both fields. +# Strict CI classification: +# pending — any item still running (IN_PROGRESS/QUEUED/WAITING/PENDING/EXPECTED +# or COMPLETED with null/empty conclusion) +# passing — all items completed AND every conclusion is SUCCESS, SKIPPED, or +# NEUTRAL (or rollup empty). SKIPPED covers path-filtered checks; +# NEUTRAL covers informational checks that don't gate merging. +# failing — anything else (FAILURE, ACTION_REQUIRED, TIMED_OUT, CANCELLED, +# STALE, STARTUP_FAILURE, or unknown conclusions) +PR_SNAPSHOT=$(gh pr view "$PR_URL" --json headRefOid,statusCheckRollup) +PR_HEAD_SHA=$(echo "$PR_SNAPSHOT" | jq -r '.headRefOid') export PR_HEAD_SHA echo " head SHA: $PR_HEAD_SHA" +CI_STATUS=$(echo "$PR_SNAPSHOT" | jq -r ' + def is_pending: + .status == "IN_PROGRESS" or .status == "QUEUED" or .status == "WAITING" or + .state == "PENDING" or .state == "EXPECTED" or + (.status == "COMPLETED" and (.conclusion == null or .conclusion == "")); + def is_success: + .conclusion == "SUCCESS" or .conclusion == "SKIPPED" or .conclusion == "NEUTRAL" or + .state == "SUCCESS"; + if (.statusCheckRollup | length) == 0 then "passing" + elif ([.statusCheckRollup[] | select(is_pending)] | length) > 0 then "pending" + elif ([.statusCheckRollup[] | select(is_success)] | length) == (.statusCheckRollup | length) then "passing" + else "failing" + end +') +echo " CI status: $CI_STATUS" + +# Exit code 100 is the skip sentinel: the caller treats any 100 exit as a +# no-op and does not count it against the MAX_PRS review budget. +# Reasons that produce a skip: already-reviewed-at-head, ci-failing, ci-pending. +if [ "$CI_STATUS" = "failing" ]; then + echo " skip: CI checks are failing — will re-evaluate after fixes are pushed" + echo "{\"pr\":\"$PR_URL\",\"sha\":\"$PR_HEAD_SHA\",\"decision\":\"skip\",\"reason\":\"ci-failing\"}" + exit 100 +fi +if [ "$CI_STATUS" = "pending" ]; then + echo " skip: CI checks still in progress — will re-evaluate when checks complete" + echo "{\"pr\":\"$PR_URL\",\"sha\":\"$PR_HEAD_SHA\",\"decision\":\"skip\",\"reason\":\"ci-pending\"}" + exit 100 +fi + # 2. Idempotency: look for our marker at this SHA in existing reviews+comments # Extract the most recent SHA from our review marker in existing PR comments/reviews. # Uses (array + array) to concatenate safely when either is empty, then iterates