diff --git a/.github/workflows/pr-review.yml b/.github/workflows/pr-review.yml index d0c251b57..8db6f57b2 100644 --- a/.github/workflows/pr-review.yml +++ b/.github/workflows/pr-review.yml @@ -15,6 +15,16 @@ on: required: false default: "false" type: string + force_review: + description: "If true, bypass idempotency check and re-review even if already reviewed at head SHA (use for @mention-triggered reviews)" + required: false + default: "false" + type: string + repository_dispatch: + # Triggered by the petry-projects/.github mention-listener workflow. + # Requires only Contents: write on this repo (not Actions: write). + # Payload: { pr_url: "https://github.com/...", force_review: "true" } + types: [pr-review-mention] permissions: contents: read @@ -22,7 +32,10 @@ permissions: checks: read concurrency: - group: pr-review + # Scheduled and manual batch runs share one slot to prevent overlap. + # Mention-triggered runs (repository_dispatch or workflow_dispatch with pr_url) + # get per-PR slots so they don't queue behind hourly batches or each other. + group: ${{ (inputs.pr_url || github.event.client_payload.pr_url) && format('pr-review-mention-{0}', inputs.pr_url || github.event.client_payload.pr_url) || 'pr-review-scheduled' }} cancel-in-progress: false jobs: @@ -40,16 +53,20 @@ jobs: # No new secret needed: gh secret set GH_PAT is already present in this repo. COPILOT_GITHUB_TOKEN: ${{ secrets.GH_PAT }} # Default to dry-run unless the repo variable LIVE_MODE is set to 'true'. - # Manual workflow_dispatch can override either way via the dry_run input. + # workflow_dispatch can override via dry_run input. + # repository_dispatch (mention trigger) always runs live — the human explicitly asked. # To go live: gh variable set LIVE_MODE --body true --repo don-petry/self - DRY_RUN: ${{ inputs.dry_run || (vars.LIVE_MODE == 'true' && 'false' || 'true') }} - PR_URL_OVERRIDE: ${{ inputs.pr_url }} + DRY_RUN: ${{ github.event_name == 'repository_dispatch' && 'false' || inputs.dry_run || (vars.LIVE_MODE == 'true' && 'false' || 'true') }} + PR_URL_OVERRIDE: ${{ inputs.pr_url || github.event.client_payload.pr_url }} # Comma-separated list of GitHub orgs where AI delegation is enabled. # When findings exist, the agent posts fix-request comments for AI to act on. # gh variable set DELEGATION_ORGS --body "petry-projects,don-petry" --repo don-petry/self DELEGATION_ORGS: ${{ vars.DELEGATION_ORGS || vars.CLAUDE_ORGS || '' }} # Max review cycles before stopping AI delegation and escalating to human. MAX_REVIEW_CYCLES: ${{ vars.MAX_REVIEW_CYCLES || '3' }} + # When true, bypass idempotency check so an @mention always triggers a fresh review. + # repository_dispatch always forces a review; workflow_dispatch respects the input. + FORCE_REVIEW: ${{ github.event_name == 'repository_dispatch' && 'true' || inputs.force_review || 'false' }} steps: - name: Checkout agent repo diff --git a/AGENT.md b/AGENT.md index ca4abd1c5..f6c992707 100644 --- a/AGENT.md +++ b/AGENT.md @@ -11,6 +11,8 @@ and **Copilot**. 1. **Cron** — `.github/workflows/pr-review.yml` runs at `:07` every hour (and on `workflow_dispatch`). +1a. **@mention** — comment `@petry-review-bot` on any PR to trigger an immediate + review, bypassing the hourly schedule. See [Mention-triggered reviews](#mention-triggered-reviews). 2. **Enumerate** — `scripts/list-prs.sh` queries GitHub for open PRs where `@me` is the author OR a requested reviewer, across every repo the PAT can see. Output: one URL per line. @@ -239,6 +241,46 @@ gh workflow run pr-review.yml --repo don-petry/pr-review-agent -f dry_run=false job timeout. Override: `gh variable set MAX_PRS --body 15 --repo don-petry/pr-review-agent` +## Mention-triggered reviews + +Comment `@petry-review-bot` on any PR to start an immediate, on-demand review +without waiting for the next scheduled run. The bot posts an acknowledgement +within seconds and the full cascade result appears in a few minutes. + +**How it flows:** + +``` +PR comment "@petry-review-bot please review" + → petry-projects/.github: pr-review-mention.yml (listens org-wide) + → validates commenter trust (OWNER/MEMBER/COLLABORATOR only) + → posts ack comment "I'm on it..." + → gh workflow run pr-review.yml --field pr_url= --field force_review=true + → don-petry/pr-review-agent: pr-review.yml (per-PR concurrency slot) + → scripts/review-one-pr.sh (FORCE_REVIEW=true bypasses idempotency) + → cascade as normal → posts review +``` + +**Key behaviors vs. scheduled runs:** +- `force_review=true` skips the "already reviewed at this SHA" no-op, so you + always get a fresh analysis even if the head commit hasn't changed. +- Each mention-triggered run uses its own concurrency group (`pr-review-mention-`) + so it doesn't queue behind hourly batch runs or other mentions. +- Commenter trust is enforced — external contributors cannot trigger reviews. + +**Setup (one-time):** + +1. Copy [`templates/mention-listener.yml`](templates/mention-listener.yml) to + `petry-projects/.github` as `.github/workflows/pr-review-mention.yml`. + +2. Add the `DON_PETRY_BOT_PETRY_PROJECT_PAT` secret to `petry-projects/.github` + (org-level secret or repo secret on `.github`). The PAT needs: + - **Pull requests: write** — to post the ack comment across petry-projects repos + - **Contents: write** (scoped to `don-petry/pr-review-agent`) — to send the + `repository_dispatch` event (does **not** require `Actions: write`) + +3. Ensure `petry-review-bot` has at least **Read** collaborator access on + `don-petry/pr-review-agent`. + ## Architecture ``` diff --git a/scripts/review-one-pr.sh b/scripts/review-one-pr.sh index 5a90a1043..c4b648c1f 100755 --- a/scripts/review-one-pr.sh +++ b/scripts/review-one-pr.sh @@ -98,11 +98,15 @@ EXISTING_MARKER_SHA=$( ) if [ -n "${EXISTING_MARKER_SHA:-}" ] && [ "$EXISTING_MARKER_SHA" = "$PR_HEAD_SHA" ]; then - echo " noop: already reviewed at $PR_HEAD_SHA" - echo "{\"pr\":\"$PR_URL\",\"sha\":\"$PR_HEAD_SHA\",\"decision\":\"noop\",\"reason\":\"already-reviewed-at-head\"}" - # Exit 100 is the no-op sentinel: the caller can skip this PR without - # counting it against the MAX_PRS budget of actual reviews. - exit 100 + if [ "${FORCE_REVIEW:-false}" = "true" ]; then + echo " force-review: prior marker $PR_HEAD_SHA matches head, but FORCE_REVIEW=true — re-running cascade" + else + echo " noop: already reviewed at $PR_HEAD_SHA" + echo "{\"pr\":\"$PR_URL\",\"sha\":\"$PR_HEAD_SHA\",\"decision\":\"noop\",\"reason\":\"already-reviewed-at-head\"}" + # Exit 100 is the no-op sentinel: the caller can skip this PR without + # counting it against the MAX_PRS budget of actual reviews. + exit 100 + fi fi if [ -n "${EXISTING_MARKER_SHA:-}" ]; then diff --git a/templates/mention-listener.yml b/templates/mention-listener.yml new file mode 100644 index 000000000..e18c8d45c --- /dev/null +++ b/templates/mention-listener.yml @@ -0,0 +1,100 @@ +# Deploy this file to petry-projects/.github as: +# .github/workflows/pr-review-mention.yml +# +# Purpose: Trigger the pr-review-agent whenever @petry-review-bot is mentioned +# in a PR comment or review comment within the petry-projects org. +# +# Prerequisites: +# 1. Add secret DON_PETRY_BOT_PETRY_PROJECT_PAT to petry-projects/.github +# with the bot PAT that has: +# - Contents: write (scoped to don-petry/pr-review-agent) — for repository_dispatch +# - Pull requests: write (org-wide or per-repo) — to post the ack comment +# 2. The PAT owner (petry-review-bot) does NOT need Actions: write. +# Read-level collaborator access on don-petry/pr-review-agent is sufficient. + +name: PR Review — Mention Trigger + +on: + issue_comment: + types: [created] + pull_request_review_comment: + types: [created] + +permissions: + pull-requests: write + +jobs: + handle-mention: + runs-on: ubuntu-latest + # Only fire when @petry-review-bot appears in the comment body. + # For issue_comment events, also require that the comment is on a PR (not a plain issue). + if: | + contains(github.event.comment.body, '@petry-review-bot') && + (github.event_name == 'pull_request_review_comment' || + github.event.issue.pull_request != null) + + steps: + - name: Check commenter trust level + id: trust + env: + GH_TOKEN: ${{ secrets.DON_PETRY_BOT_PETRY_PROJECT_PAT }} + AUTHOR_ASSOCIATION: ${{ github.event.comment.author_association }} + COMMENTER: ${{ github.event.comment.user.login }} + run: | + # Only OWNER, MEMBER, and COLLABORATOR can trigger reviews. + # This prevents external contributors or bots from burning review quota. + case "$AUTHOR_ASSOCIATION" in + OWNER|MEMBER|COLLABORATOR) + echo "trusted=true" >> "$GITHUB_OUTPUT" + echo "Commenter @$COMMENTER has association $AUTHOR_ASSOCIATION — trusted" + ;; + *) + echo "trusted=false" >> "$GITHUB_OUTPUT" + echo "Commenter @$COMMENTER has association $AUTHOR_ASSOCIATION — not trusted, skipping" + ;; + esac + + - name: Resolve PR URL + id: pr + if: steps.trust.outputs.trusted == 'true' + env: + GH_TOKEN: ${{ secrets.DON_PETRY_BOT_PETRY_PROJECT_PAT }} + run: | + if [ "${{ github.event_name }}" = "pull_request_review_comment" ]; then + PR_URL="${{ github.event.pull_request.html_url }}" + else + # issue_comment: resolve the PR URL from the issue's pull_request link + PR_URL=$(gh api "${{ github.event.issue.pull_request.url }}" --jq '.html_url') + fi + echo "pr_url=$PR_URL" >> "$GITHUB_OUTPUT" + echo "PR URL: $PR_URL" + + - name: Post acknowledgement comment + if: steps.trust.outputs.trusted == 'true' + env: + GH_TOKEN: ${{ secrets.DON_PETRY_BOT_PETRY_PROJECT_PAT }} + PR_URL: ${{ steps.pr.outputs.pr_url }} + COMMENTER: ${{ github.event.comment.user.login }} + run: | + gh pr comment "$PR_URL" --body "$(cat <<'EOF' + + @'"$COMMENTER"' I'm on it — starting a fresh review now. Results will appear in a few minutes. + EOF + )" + + - name: Trigger review agent + if: steps.trust.outputs.trusted == 'true' + env: + GH_TOKEN: ${{ secrets.DON_PETRY_BOT_PETRY_PROJECT_PAT }} + PR_URL: ${{ steps.pr.outputs.pr_url }} + run: | + # Use repository_dispatch (requires only Contents: write, not Actions: write). + # pr-review.yml listens for type "pr-review-mention" and extracts + # client_payload.pr_url to run the cascade. + gh api \ + --method POST \ + --header "Accept: application/vnd.github+json" \ + /repos/don-petry/pr-review-agent/dispatches \ + --field event_type=pr-review-mention \ + --field "client_payload[pr_url]=$PR_URL" + echo "Dispatch sent for $PR_URL"