Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

feat: auto-respond to reviews and comments on bot-engaged PRs (#1163)

Maximilian Roosb735560603b2
diff --git a/.claude/skills/pr-review/SKILL.md b/.claude/skills/pr-review/SKILL.md
index 851146139..7b344b289 100644
--- a/.claude/skills/pr-review/SKILL.md
+++ b/.claude/skills/pr-review/SKILL.md
@@ -328,29 +328,19 @@ fixed line content here
direct suggestion.
- Multi-line suggestions: set `start_line` and `line` to define the range.
-### 6. Request fixes on bot PRs
+### 6. Request fixes when the author won't respond
-The review workflow is read-only (`contents: read`) and cannot push fixes. For
-bot PRs (Dependabot, renovate, etc.), request fixes via the `@worktrunk-bot` mention
-workflow, which has write access and can push commits to the PR branch.
-
-**When to use:** The review found concrete, fixable issues (CI failures, missing
-test updates, small code problems) on a bot-authored PR. Don't use this for
-human PRs — leave suggestions for the author instead.
-
-After submitting the review, post a separate comment:
+If the review found concrete, fixable issues on a PR where the author won't act
+on feedback (Dependabot, renovate, etc.), post a `@worktrunk-bot` comment:
```bash
-gh pr comment <number> --body "@worktrunk-bot The review found issues on this Dependabot PR. Please fix:
+gh pr comment <number> --body "@worktrunk-bot Please fix the issues from the review:
- [specific issue 1]
-- [specific issue 2]
-
-See the review comments for details."
+- [specific issue 2]"
```
-This triggers the `claude-mention` workflow, which checks out the PR branch,
-applies fixes, and pushes. CI reruns automatically.
+For human PRs, leave suggestions for the author instead.
## What makes good review feedback
diff --git a/.github/CLAUDE.md b/.github/CLAUDE.md
index f33e7ec71..1a2c5b15e 100644
--- a/.github/CLAUDE.md
+++ b/.github/CLAUDE.md
@@ -45,14 +45,14 @@ Environment protection prevents this: secrets in a protected environment are onl
| Capability | Triage | Mention | Review | CI Fix | Renovate |
|------------|:---:|:---:|:---:|:---:|:---:|
| Read issues/PRs | Yes | Yes | Yes | Yes | — |
-| Comment on issues | Yes | Yes | — | — | — |
-| Create branches | Yes | Yes | — | Yes | Yes |
-| Push commits | Yes | Yes | — | Yes | Yes |
+| Comment on issues | Yes | Yes | Yes | — | — |
+| Create branches | Yes | Yes | Yes | Yes | Yes |
+| Push commits | Yes | Yes | Yes | Yes | Yes |
| Create PRs | Yes | Yes | — | Yes | Yes |
| Post PR reviews | — | — | Yes | — | — |
| Resolve review threads | — | — | Yes | — | — |
-| Monitor CI | Yes | Yes | — | Yes | Yes |
-| **Pushes must trigger CI** | **Yes** | **Yes** | — | **Yes** | **Yes** |
+| Monitor CI | Yes | Yes | Yes | Yes | Yes |
+| **Pushes must trigger CI** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** |
The last row matters for CI: `GITHUB_TOKEN` pushes don't trigger downstream workflows (GitHub prevents infinite loops). Workflows that push code and need CI to run **must** use a PAT. All Claude workflows use `WORKTRUNK_BOT_TOKEN` for consistent identity.
@@ -88,15 +88,15 @@ Two independent authentication paths exist in every workflow:
1. **Git CLI** (`git push`): authenticates with the token from `actions/checkout`. When no explicit token is passed, this defaults to `GITHUB_TOKEN` scoped by the `permissions:` block. When an explicit token is passed (e.g. `token: ${{ secrets.WORKTRUNK_BOT_TOKEN }}`), the PAT's scopes apply instead.
2. **GitHub API** (`gh pr create`, `gh api`): `claude-code-action` overwrites the `GITHUB_TOKEN` env var with its `github_token` input (BOT_TOKEN for all Claude workflows).
-The review workflow is the only one where these paths diverge: checkout uses the default `GITHUB_TOKEN` (`contents: read`), so git CLI is read-only, while API calls use BOT_TOKEN. All other workflows pass BOT_TOKEN to both paths.
+All workflows pass BOT_TOKEN to both paths.
## Prompt injection threat model
| Workflow | Injection surface | Attacker control | Mitigations |
|----------|-------------------|-------------------|-------------|
-| **review** | PR diff content | Full (any external PR) | Fixed prompt, merge restriction, `contents: read` on checkout |
+| **review** | PR diff content (initial review), review body on bot PRs (respond) | Full (any external PR) / Medium (anyone who can review bot PRs) | Fixed prompt, merge restriction |
| **triage** | Issue body | Partial (structured skill) | Fixed prompt, merge restriction, environment protection |
-| **mention** | Comment body | Full | Fixed prompt, merge restriction, fork check on inline review comments |
+| **mention** | Comment body on any issue/PR, inline/conversation comments on bot-engaged PRs | Full | Fixed prompt, merge restriction, fork check on inline review comments, non-mention triggers verified against bot engagement via API |
| **ci-fix** | Failed CI logs | Minimal (must break CI on main) | Fixed prompt, automatic trigger |
| **renovate** | None | None | Fixed prompt, scheduled trigger |
@@ -111,20 +111,11 @@ The most dangerous attack from a leaked BOT_TOKEN is not merging malicious code
This is why release secrets must be in a protected environment, not repo-level secrets.
-## TODO
+## Future hardening
-### Immediate
-
-- [x] Create "Merge access" ruleset on `main`: "Restrict updates" rule, bypass actor = Repository Admin with **exempt** mode. This prevents `worktrunk-bot` (write role) from merging while giving `@max-sixty` (admin) a frictionless merge button.
-- [x] Create `release` GitHub Environment with deployment protection (require `@max-sixty` approval). Add deployment branch/tag allowlist restricting to `v*` tags so arbitrary branches can't request the environment. Leave "prevent self-approvals" off (otherwise the tag pusher can't approve their own release).
-- [x] Move `CARGO_REGISTRY_TOKEN` and `AUR_SSH_PRIVATE_KEY` from repo secrets to the `release` environment. Update `release.yaml` `publish-cargo` and `publish-aur` jobs to add `environment: release`.
-- [x] Delete `WORKTRUNK_REVIEW_TOKEN` from repo secrets
-
-### Future hardening
-
-- [ ] Consider migrating from PAT to GitHub App for ephemeral tokens (~1 hour lifetime vs indefinite PAT)
-- [ ] Consider workflow dispatch isolation: split triage/mention into analysis (GITHUB_TOKEN) + push (separate workflow with BOT_TOKEN) so the token never touches untrusted input
-- [ ] Consider disabling "Allow GitHub Actions to create and approve pull requests" in repo settings to prevent GITHUB_TOKEN from ever approving PRs
+- Migrate from PAT to GitHub App for ephemeral tokens (~1 hour lifetime vs indefinite PAT)
+- Workflow dispatch isolation: split triage/mention into analysis (GITHUB_TOKEN) + push (separate workflow with BOT_TOKEN) so the token never touches untrusted input
+- Disable "Allow GitHub Actions to create and approve pull requests" in repo settings to prevent GITHUB_TOKEN from ever approving PRs
## Triage ↔ mention handoff
@@ -134,6 +125,27 @@ These two workflows explicitly exclude each other to avoid double-processing:
The mention workflow runs for any user who includes `@worktrunk-bot` — the merge restriction (ruleset) is the safety boundary, not access control on the workflow itself.
+## Bot-engaged auto-response
+
+`worktrunk-bot` is a regular GitHub user account (PAT-based), not a GitHub App. The workflows check `user.login == 'worktrunk-bot'` directly.
+
+**Triggers a response:**
+- Non-draft PR opened or updated → automatic code review (`claude-review`)
+- Formal review submitted on a `worktrunk-bot`-authored PR, with body or non-approval → `claude-review` responds
+- `@worktrunk-bot` mentioned in an issue body → `claude-mention` responds
+- `@worktrunk-bot` mentioned in any comment (issue or PR) → `claude-mention` responds
+- Any comment on a PR or issue that `worktrunk-bot` has engaged with (authored, reviewed, or commented on) → `claude-mention` responds (verify step confirms engagement via API)
+- Editing a comment or issue body re-triggers the same response
+
+**Does not trigger:**
+- `worktrunk-bot`'s own comments or reviews (loop prevention)
+- Empty approvals on `worktrunk-bot` PRs (approved with no body)
+- Comments on issues or PRs where `worktrunk-bot` hasn't engaged and no `@worktrunk-bot` mention
+- Inline review comments on fork PRs (secrets unavailable)
+- Draft PRs
+
+**Routing:** Formal reviews (`pull_request_review`) → `claude-review`. Inline comments (`pull_request_review_comment`) and conversation comments (`issue_comment`) → `claude-mention`.
+
## GitHub API: issue_comment vs pull_request_review_comment
GitHub treats PRs as a superset of issues. Comments on a PR arrive via two different event types depending on where they're posted:
@@ -143,6 +155,14 @@ GitHub treats PRs as a superset of issues. Comments on a PR arrive via two diffe
The `claude-mention` workflow handles both with separate checkout steps.
+### pull_request_review
+
+A third event type fires when a reviewer submits a formal review (approve, comment, or request changes):
+
+- **Review submission** → `pull_request_review` event (type: `submitted`). The review is at `github.event.review` (includes `.body`, `.state`, `.user`). The PR is at `github.event.pull_request`.
+
+Individual inline comments from a review also fire as separate `pull_request_review_comment` events. The `claude-review` workflow handles `pull_request_review` for bot-authored PRs; inline comments go through `claude-mention`.
+
## Rules for modifying workflows
- **No role-based gating**: Workflows should not check `author_association` (OWNER, MEMBER, etc.) to decide whether to run. The merge restriction (ruleset) is the security boundary — Claude cannot merge regardless of who triggers it. Use technical criteria instead: fork detection, loop prevention (exclude the bot's own comments), `@worktrunk-bot` trigger phrase.
diff --git a/.github/workflows/claude-mention.yaml b/.github/workflows/claude-mention.yaml
index c8249bfc8..5e0bf8065 100644
--- a/.github/workflows/claude-mention.yaml
+++ b/.github/workflows/claude-mention.yaml
@@ -18,11 +18,15 @@ env:
jobs:
claude:
- # Run for:
- # 1. @worktrunk-bot mentions in issues/PRs/comments
- # 2. Any comment on worktrunk-bot PRs (loop prevention: exclude bot's own comments)
+ # Two triggers:
+ # 1. @worktrunk-bot mentions — explicit requests on any issue/PR.
+ # 2. Bot-engaged PRs/issues — any non-bot comment on a PR or issue
+ # where the bot has authored, reviewed, or commented. The verify step
+ # checks engagement via API and skips the job if the bot has not
+ # participated. Formal review submissions
+ # (pull_request_review) go to claude-review instead.
#
- # Always runs in agent mode (prompt). The prompt tells Claude what happened
+ # Runs in agent mode (prompt). The prompt tells Claude what happened
# and where to look; Claude reads the full context itself via gh/skills.
#
# Note: secrets cannot be used in job-level `if:` (actions/runner#520) —
@@ -30,11 +34,13 @@ jobs:
# comments on fork PRs (which don't receive secrets), we detect forks via
# github.event context instead. Use a Conversation tab comment for fork PRs.
if: |
- (github.event_name == 'issues' && contains(github.event.issue.body, '@worktrunk-bot')) ||
- (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@worktrunk-bot')) ||
- (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@worktrunk-bot') && github.event.pull_request.head.repo.full_name == github.repository) ||
- (github.event_name == 'issue_comment' && github.event.issue.pull_request && github.event.issue.user.login == 'worktrunk-bot' && github.event.comment.user.login != 'worktrunk-bot') ||
- (github.event_name == 'pull_request_review_comment' && github.event.pull_request.user.login == 'worktrunk-bot' && github.event.comment.user.login != 'worktrunk-bot' && github.event.pull_request.head.repo.full_name == github.repository)
+ (github.event_name == 'issues' &&
+ contains(github.event.issue.body, '@worktrunk-bot')) ||
+ (github.event_name == 'issue_comment' &&
+ github.event.comment.user.login != 'worktrunk-bot') ||
+ (github.event_name == 'pull_request_review_comment' &&
+ github.event.pull_request.head.repo.full_name == github.repository &&
+ github.event.comment.user.login != 'worktrunk-bot')
runs-on: ubuntu-24.04
permissions:
contents: write # Allow pushing commits
@@ -43,7 +49,54 @@ jobs:
id-token: write
actions: read # Required for Claude to read CI results on PRs
steps:
+ - name: 🔍 Verify bot engagement
+ id: verify
+ continue-on-error: true
+ if: "github.event.comment && !contains(github.event.comment.body || '', '@worktrunk-bot')"
+ run: |
+ if [ "$GITHUB_EVENT_NAME" = "issue_comment" ]; then
+ ISSUE_NUMBER="${{ github.event.issue.number }}"
+
+ if [ -z "${{ github.event.issue.pull_request.url }}" ]; then
+ # Plain issue — check if bot has commented
+ BOT_COMMENTS=$(gh api "repos/$GITHUB_REPOSITORY/issues/$ISSUE_NUMBER/comments" \
+ --jq '[.[] | select(.user.login == "worktrunk-bot")] | length')
+ if [ "$BOT_COMMENTS" -gt "0" ]; then
+ exit 0
+ fi
+ echo "::notice::Bot has not engaged with issue #$ISSUE_NUMBER — skipping"
+ exit 1
+ fi
+
+ PR_NUMBER="$ISSUE_NUMBER"
+ else
+ PR_NUMBER="${{ github.event.pull_request.number }}"
+ fi
+
+ PR_AUTHOR=$(gh pr view "$PR_NUMBER" --repo "$GITHUB_REPOSITORY" --json author --jq '.author.login')
+ if [ "$PR_AUTHOR" = "worktrunk-bot" ]; then
+ exit 0
+ fi
+
+ BOT_REVIEWS=$(gh api "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER/reviews" \
+ --jq '[.[] | select(.user.login == "worktrunk-bot")] | length')
+ if [ "$BOT_REVIEWS" -gt "0" ]; then
+ exit 0
+ fi
+
+ BOT_COMMENTS=$(gh api "repos/$GITHUB_REPOSITORY/issues/$PR_NUMBER/comments" \
+ --jq '[.[] | select(.user.login == "worktrunk-bot")] | length')
+ if [ "$BOT_COMMENTS" -gt "0" ]; then
+ exit 0
+ fi
+
+ echo "::notice::Bot has not engaged with PR #$PR_NUMBER — skipping"
+ exit 1
+ env:
+ GH_TOKEN: ${{ secrets.WORKTRUNK_BOT_TOKEN }}
+
- name: 📂 Checkout code
+ if: steps.verify.outcome != 'failure'
uses: actions/checkout@v6
with:
fetch-depth: 0
@@ -57,7 +110,7 @@ jobs:
git config --global user.email "[email protected]"
- name: 👀 React to comment
- if: github.event.comment
+ if: steps.verify.outcome != 'failure' && github.event.comment
run: |
# Try issue comment endpoint first, then review comment endpoint.
# One will match depending on the comment type.
@@ -69,7 +122,7 @@ jobs:
GH_TOKEN: ${{ secrets.WORKTRUNK_BOT_TOKEN }}
- name: 📌 Check out PR branch (conversation comment)
- if: github.event.issue.pull_request
+ if: steps.verify.outcome != 'failure' && github.event.issue.pull_request
run: |
PR_STATE=$(gh pr view ${{ github.event.issue.number }} --json state --jq '.state')
if [ "$PR_STATE" = "OPEN" ]; then
@@ -81,7 +134,7 @@ jobs:
GH_TOKEN: ${{ secrets.WORKTRUNK_BOT_TOKEN }}
- name: 📌 Check out PR branch (review comment)
- if: github.event_name == 'pull_request_review_comment'
+ if: steps.verify.outcome != 'failure' && github.event_name == 'pull_request_review_comment'
run: |
PR_STATE=$(gh pr view ${{ github.event.pull_request.number }} --json state --jq '.state')
if [ "$PR_STATE" = "OPEN" ]; then
@@ -114,6 +167,7 @@ jobs:
sudo apt-get install -y zsh fish
- name: 🤖 Run Claude Code
+ if: steps.verify.outcome != 'failure'
id: claude
uses: anthropics/claude-code-action@v1
with:
diff --git a/.github/workflows/claude-review.yaml b/.github/workflows/claude-review.yaml
index 929368f64..3df7d3ea6 100644
--- a/.github/workflows/claude-review.yaml
+++ b/.github/workflows/claude-review.yaml
@@ -1,60 +1,104 @@
name: claude-review
# Runner versions pinned; see ci.yaml header comment for rationale.
-# Automatic code review on non-draft PRs.
-# Uses pull_request_target so secrets are available for fork PRs.
+# Two modes in one job:
+# - pull_request_target: automatic code review on non-draft PRs.
+# - pull_request_review: respond to formal reviews on bot-authored PRs.
on:
pull_request_target:
types: [opened, synchronize, ready_for_review, reopened]
+ pull_request_review:
+ types: [submitted]
concurrency:
- group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+ group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.event.pull_request.number }}
cancel-in-progress: true
env:
CARGO_TERM_COLOR: always
CLICOLOR_FORCE: 1
+ RUSTFLAGS: "-C debuginfo=0"
+ RUSTDOCFLAGS: "-Dwarnings"
jobs:
- review:
- # Skip draft PRs.
- # To skip PRs from repo members, uncomment the author_association conditions:
- # github.event.pull_request.author_association != 'OWNER' &&
- # github.event.pull_request.author_association != 'MEMBER' &&
- if: >-
- github.event.pull_request.draft == false
+ claude:
+ if: |
+ (github.event_name == 'pull_request_target' &&
+ github.event.pull_request.draft == false) ||
+ (github.event_name == 'pull_request_review' &&
+ github.event.pull_request.user.login == 'worktrunk-bot' &&
+ github.event.review.user.login != 'worktrunk-bot' &&
+ (github.event.review.state != 'approved' || github.event.review.body))
runs-on: ubuntu-24.04
permissions:
- contents: read # Read-only: review workflow should not push code
+ contents: write
pull-requests: write
issues: write
id-token: write
actions: read
steps:
- - name: 📂 Checkout code
+ - name: 📂 Checkout merge commit (initial review)
+ if: github.event_name == 'pull_request_target'
uses: actions/checkout@v6
with:
ref: refs/pull/${{ github.event.pull_request.number }}/merge
fetch-depth: 0
+ token: ${{ secrets.WORKTRUNK_BOT_TOKEN }}
+
+ - name: 📂 Checkout code (review response)
+ if: github.event_name == 'pull_request_review'
+ uses: actions/checkout@v6
+ with:
+ fetch-depth: 0
+ fetch-tags: true
+ token: ${{ secrets.WORKTRUNK_BOT_TOKEN }}
- name: 🔧 Configure git for Claude
run: |
git config --global user.name "Claude Code"
git config --global user.email "[email protected]"
- - name: 🤖 Review PR with Claude
+ - name: 📌 Check out PR branch
+ if: github.event_name == 'pull_request_review'
+ run: gh pr checkout ${{ github.event.pull_request.number }}
+ env:
+ GH_TOKEN: ${{ secrets.WORKTRUNK_BOT_TOKEN }}
+
+ - name: Install cargo-insta
+ if: github.event_name == 'pull_request_review'
+ uses: baptiste0928/cargo-install@v3
+ with:
+ crate: cargo-insta
+
+ - name: Install cargo-nextest
+ if: github.event_name == 'pull_request_review'
+ uses: baptiste0928/cargo-install@v3
+ with:
+ crate: cargo-nextest
+
+ - name: 💰 Cache
+ if: github.event_name == 'pull_request_review'
+ uses: Swatinem/rust-cache@v2
+ with:
+ prefix-key: ${{ hashFiles('Cargo.lock') }}
+ save-if: false
+
+ - name: Install shells (zsh, fish)
+ if: github.event_name == 'pull_request_review'
+ run: |
+ sudo apt-get update
+ sudo apt-get install -y zsh fish
+
+ - name: 🤖 Run Claude Code
+ id: claude
uses: anthropics/claude-code-action@v1
with:
claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
- # BOT_TOKEN so reviews post as worktrunk-bot (not github-actions[bot]).
- # Merge restriction (ruleset) is the security boundary, not token
- # scoping. See .github/CLAUDE.md.
github_token: ${{ secrets.WORKTRUNK_BOT_TOKEN }}
additional_permissions: |
actions: read
- use_sticky_comment: true
- prompt: |
- Use /pr-review ${{ github.event.pull_request.number }}
+ use_sticky_comment: ${{ github.event_name == 'pull_request_target' }}
+ prompt: ${{ github.event_name == 'pull_request_target' && format('Use /pr-review {0}', github.event.pull_request.number) || '' }}
claude_args: |
--model opus
--allowedTools Bash,Edit,Read,Write,Glob,Grep,WebSearch,WebFetch,Task,Skill