> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paddock.build/llms.txt
> Use this file to discover all available pages before exploring further.

# Pull request reviewer on GitHub

> An agent that reviews every pull request of a repository, and answers when someone mentions it, with no server of your own.

This example builds `pr-reviewer`: an agent that reviews a pull request when it is opened or updated, and answers when someone mentions `@pr-reviewer` in the pull request's conversation. Each pull request gets one session, so a later push or question is handled with the earlier review in context. GitHub posts its webhooks straight to a paddock trigger; you run no server.

```mermaid theme={null}
sequenceDiagram
  participant GitHub
  participant Trigger as paddock trigger
  participant Agent as pr-reviewer (session per PR)
  GitHub->>Trigger: pull_request opened, #42
  Trigger->>Agent: new session acme/web#42: "Review it"
  Agent->>GitHub: review with inline comments (GitHub MCP server)
  GitHub->>Trigger: pull_request synchronize, #42
  Trigger->>Agent: same session: "Review what changed"
  GitHub->>Trigger: issue_comment "@pr-reviewer why?"
  Trigger->>Agent: same session: answer the question
```

The examples use the repository `acme/web`; replace it with yours.

## 1. The template

The template describes the reviewer: Claude Code on `claude-opus`, and a system prompt that fixes what it may do and how it must post. The agent reaches GitHub only through the GitHub MCP server, which the agent gets in the next step with your token.

```yaml agents/pr-reviewer/template.yaml theme={null}
apiVersion: paddock.build/v1
kind: Template
metadata:
  name: pr-reviewer
spec:
  harness: claude-code
  model: claude-opus
  system_prompt: |
    You are pr-reviewer, the code reviewer of github.com/acme/web.

    # Output contract (mandatory, check before every post)
    - Reviews: pull_request_review_write with event "COMMENT", always.
    - Every review body and every comment begins with this exact first line: <!-- pr-reviewer -->
    - A review body has exactly this shape, findings ranked blocker > major > minor:
        <!-- pr-reviewer -->
        **2 findings**
        1. **[major]** `path/to/file:42` What is wrong, in one or two sentences. Fix: the concrete change.
        2. **[minor]** `path/to/other:7` ... Fix: ...
      or, when there is nothing:
        <!-- pr-reviewer -->
        **No issues found.** One sentence on what you checked.
      Put the same findings inline on their lines, with a suggestion block when the fix is a line change.
    - Never write the at-sign directly followed by pr-reviewer anywhere (it would trigger you again).
    - After posting, end the turn with one line naming what you posted.

    # Tools
    Only the github MCP server: pull_request_read (get, get_diff, get_files, get_commits), get_commit,
    get_file_contents (ref = the head SHA), search_code, pull_request_review_write,
    add_comment_to_pending_review, add_issue_comment.
    Never push, commit, merge, close, or edit anything.

    # Reviewing (pull request opened, reopened, ready_for_review, synchronize)
    This session is one pull request; your earlier reviews of it are in your context.
    1. Read the pull request and its diff. On synchronize, review only the commits after the head SHA of
       your previous review; if they change nothing reviewable, post nothing. In the body, add one line
       after the count naming earlier findings now fixed or still open.
    2. Read the context the diff needs: callers and tests of changed code, and the docs it touches.
       Verify every claim against the files.
    3. Report only verified, real problems: correctness, missing tests, docs made false by the change,
       credentials committed or logged. No style nits, no praise, no restating the diff.

    # Mentions
    Answer with one add_issue_comment reply, at most 10 lines, direct, citing path:line where useful.
```

> [!TIP]
>
> Claude Code follows the review content of a system prompt readily, but output rules, such as the review event and the marker line, hold best when they come first as a contract and are repeated in each message. The rules below repeat them.

## 2. The agent

Create the template and an agent from it, then give the agent the GitHub MCP server with a GitHub token that can read the repository and write reviews and comments. The token is the agent's own configuration, so no template version ever carries it.

```go Go theme={null}
tpl, err := client.Templates.Create(ctx, "./agents/pr-reviewer/template.yaml")
if err != nil {
	return err
}
agent, err := client.Agents.Create(ctx, paddock.AgentCreate{Template: fmt.Sprintf("%s@%d", tpl.Name, tpl.Version)})
if err != nil {
	return err
}
_, err = agent.MCP.Add(ctx, paddock.McpEntry{
	Name:    "github",
	URL:     "https://api.githubcopilot.com/mcp/",
	Headers: map[string]string{"Authorization": "Bearer " + os.Getenv("GITHUB_TOKEN")},
})
```

```python Python theme={null}
import os

template = client.templates.create("./agents/pr-reviewer/template.yaml")
agent = client.agents.create(template=f"{template.name}@{template.version}")
agent.mcp.add(
    {
        "name": "github",
        "url": "https://api.githubcopilot.com/mcp/",
        "headers": {"Authorization": f"Bearer {os.environ['GITHUB_TOKEN']}"},
    }
)
```

```ts TypeScript theme={null}
const template = await paddock.templates.create("./agents/pr-reviewer/template.yaml");
const agent = await paddock.agents.create({ template: `${template.name}@${template.version}` });
await agent.mcp.add({
  name: "github",
  url: "https://api.githubcopilot.com/mcp/",
  headers: { Authorization: `Bearer ${process.env.GITHUB_TOKEN}` },
});
```

Keep `GITHUB_TOKEN` in your environment, never in code. In the console, the agent's **Capabilities** tab adds the same MCP server. After the agent's first turn, its [harness status](https://docs.paddock.build/guides/harness-status.md) shows the `github` server as `loaded`.

## 3. The trigger

The trigger checks GitHub's signature with a secret you generate (for example `openssl rand -hex 32`), drops GitHub's redeliveries by their `X-GitHub-Delivery` header, and has two rules:

* **review**: a pull request opened, updated, reopened, or marked ready, and not a draft.
* **mention**: a new comment on a pull request that mentions `@pr-reviewer`. It skips the agent's own comments, which carry the `<!-- pr-reviewer -->` marker, and comments by bots, so the agent never triggers itself.

Both rules render the same session key for a pull request, because GitHub numbers a pull request as an issue: a mention lands in the session of that pull request's review.

```go Go theme={null}
review := `Pull request {{body.repository.full_name}}#{{body.pull_request.number}} was {{body.action}} by {{body.sender.login}}.
Title: {{body.pull_request.title}}
Base: {{body.pull_request.base.ref}} ({{body.pull_request.base.sha}})
Head: {{body.pull_request.head.ref}} ({{body.pull_request.head.sha}})
Previous head (synchronize only): {{body.before}}
{{body.pull_request.html_url}}

Review it (on synchronize, only what changed since your previous review) and post one review that follows your output contract: event COMMENT, first line <!-- pr-reviewer -->, ranked findings.`
mention := `{{body.comment.user.login}} mentioned you on pull request {{body.repository.full_name}}#{{body.issue.number}} ({{body.issue.html_url}}), comment {{body.comment.html_url}}:

{{body.comment.body}}

Answer in one reply comment on the pull request that follows your output contract (first line <!-- pr-reviewer -->).`

trigger, err := client.Triggers.Create(ctx, paddock.TriggerCreate{
	Name:         "GitHub acme/web",
	Verification: &paddock.VerificationCreate{Header: "X-Hub-Signature-256", Prefix: "sha256="},
	Secret:       os.Getenv("GITHUB_WEBHOOK_SECRET"),
	Dedupe:       paddock.Ptr(`headers["x-github-delivery"]`),
	Rules: []paddock.RuleCreate{
		{
			Name:    "review",
			AgentID: agent.ID,
			Filter: paddock.Ptr(`headers["x-github-event"] == "pull_request"
  && body.repository.full_name == "acme/web"
  && body.action in ["opened", "synchronize", "reopened", "ready_for_review"]
  && !body.pull_request.draft`),
			Session: paddock.SessionChoiceKey("{{body.repository.full_name}}#{{body.pull_request.number}}"),
			Message: review,
		},
		{
			Name:    "mention",
			AgentID: agent.ID,
			Filter: paddock.Ptr(`headers["x-github-event"] == "issue_comment"
  && body.repository.full_name == "acme/web"
  && body.action == "created"
  && has(body.issue.pull_request)
  && body.comment.body.contains("@pr-reviewer")
  && !body.comment.body.contains("<!-- pr-reviewer -->")
  && body.comment.user.type != "Bot"`),
			Session: paddock.SessionChoiceKey("{{body.repository.full_name}}#{{body.issue.number}}"),
			Message: mention,
		},
	},
})
if err != nil {
	return err
}
fmt.Println(trigger.URL) // the payload URL for GitHub
```

```python Python theme={null}
import os

review = """Pull request {{body.repository.full_name}}#{{body.pull_request.number}} was {{body.action}} by {{body.sender.login}}.
Title: {{body.pull_request.title}}
Base: {{body.pull_request.base.ref}} ({{body.pull_request.base.sha}})
Head: {{body.pull_request.head.ref}} ({{body.pull_request.head.sha}})
Previous head (synchronize only): {{body.before}}
{{body.pull_request.html_url}}

Review it (on synchronize, only what changed since your previous review) and post one review that follows your output contract: event COMMENT, first line <!-- pr-reviewer -->, ranked findings."""

mention = """{{body.comment.user.login}} mentioned you on pull request {{body.repository.full_name}}#{{body.issue.number}} ({{body.issue.html_url}}), comment {{body.comment.html_url}}:

{{body.comment.body}}

Answer in one reply comment on the pull request that follows your output contract (first line <!-- pr-reviewer -->)."""

trigger = client.triggers.create(
    {
        "name": "GitHub acme/web",
        "verification": {"header": "X-Hub-Signature-256", "prefix": "sha256="},
        "secret": os.environ["GITHUB_WEBHOOK_SECRET"],
        "dedupe": 'headers["x-github-delivery"]',
        "rules": [
            {
                "name": "review",
                "agentId": agent.id,
                "filter": '''headers["x-github-event"] == "pull_request"
  && body.repository.full_name == "acme/web"
  && body.action in ["opened", "synchronize", "reopened", "ready_for_review"]
  && !body.pull_request.draft''',
                "session": {"mode": "key", "key": "{{body.repository.full_name}}#{{body.pull_request.number}}"},
                "message": review,
            },
            {
                "name": "mention",
                "agentId": agent.id,
                "filter": '''headers["x-github-event"] == "issue_comment"
  && body.repository.full_name == "acme/web"
  && body.action == "created"
  && has(body.issue.pull_request)
  && body.comment.body.contains("@pr-reviewer")
  && !body.comment.body.contains("<!-- pr-reviewer -->")
  && body.comment.user.type != "Bot"''',
                "session": {"mode": "key", "key": "{{body.repository.full_name}}#{{body.issue.number}}"},
                "message": mention,
            },
        ],
    }
)
print(trigger.url)  # the payload URL for GitHub
```

```ts TypeScript theme={null}
const trigger = await paddock.triggers.create({
  name: "GitHub acme/web",
  verification: { header: "X-Hub-Signature-256", prefix: "sha256=" },
  secret: process.env.GITHUB_WEBHOOK_SECRET,
  dedupe: 'headers["x-github-delivery"]',
  rules: [
    {
      name: "review",
      agentId: agent.id,
      filter: `headers["x-github-event"] == "pull_request"
  && body.repository.full_name == "acme/web"
  && body.action in ["opened", "synchronize", "reopened", "ready_for_review"]
  && !body.pull_request.draft`,
      session: { mode: "key", key: "{{body.repository.full_name}}#{{body.pull_request.number}}" },
      message: `Pull request {{body.repository.full_name}}#{{body.pull_request.number}} was {{body.action}} by {{body.sender.login}}.
Title: {{body.pull_request.title}}
Base: {{body.pull_request.base.ref}} ({{body.pull_request.base.sha}})
Head: {{body.pull_request.head.ref}} ({{body.pull_request.head.sha}})
Previous head (synchronize only): {{body.before}}
{{body.pull_request.html_url}}

Review it (on synchronize, only what changed since your previous review) and post one review that follows your output contract: event COMMENT, first line <!-- pr-reviewer -->, ranked findings.`,
    },
    {
      name: "mention",
      agentId: agent.id,
      filter: `headers["x-github-event"] == "issue_comment"
  && body.repository.full_name == "acme/web"
  && body.action == "created"
  && has(body.issue.pull_request)
  && body.comment.body.contains("@pr-reviewer")
  && !body.comment.body.contains("<!-- pr-reviewer -->")
  && body.comment.user.type != "Bot"`,
      session: { mode: "key", key: "{{body.repository.full_name}}#{{body.issue.number}}" },
      message: `{{body.comment.user.login}} mentioned you on pull request {{body.repository.full_name}}#{{body.issue.number}} ({{body.issue.html_url}}), comment {{body.comment.html_url}}:

{{body.comment.body}}

Answer in one reply comment on the pull request that follows your output contract (first line <!-- pr-reviewer -->).`,
    },
  ],
});
console.log(trigger.url); // the payload URL for GitHub
```

Before you connect GitHub, run the rules on sample events with `triggers.test`, or in the console's rule editor, whose test panel shows each rule's match, session key, and message as you type. A synchronize event should match `review`, a draft or a ping should be filtered, and a comment carrying the marker should not match `mention`.

## 4. The GitHub webhook

In the repository's **Settings → Webhooks → Add webhook**:

| Setting | Value |
| - | - |
| Payload URL | `trigger.url` |
| Content type | `application/json` |
| Secret | The same `GITHUB_WEBHOOK_SECRET` you gave the trigger |
| Events | **Let me select individual events**: **Pull requests** and **Issue comments** |
| Active | Checked |

GitHub sends a `ping` when you save the webhook. It shows in the trigger's deliveries with both rules `filtered`: its `x-github-event` is `ping`, and `&&` stops before reading fields a ping lacks.

## What happens

| Event | Rule outcomes | Result |
| - | - | - |
| `pull_request` opened, #42 | `review` delivered, `sessionCreated: true` | A new session with `triggerKey` `acme/web#42`; the agent reads the pull request and posts its review |
| `pull_request` synchronize, #42 | `review` delivered to the same session | The agent reviews only the new commits, with its first review in context |
| `issue_comment` on #42 mentioning `@pr-reviewer` | `mention` delivered to the same session | The agent answers on the pull request |
| The agent's own reply comment | Both filtered | Nothing: the marker stops the loop |
| GitHub redelivers an event with the same `X-GitHub-Delivery` | None | `200` with `duplicate: true` |
| `pull_request` opened, #43 | `review` delivered | A second session, `acme/web#43`, on the same agent and sandbox |
| A request with a wrong signature | None | Rejected with `401`, recorded as `bad_signature` |

Find a pull request's conversation with `sessions.list({ metadata: { triggerKey: "acme/web#42" } })`, or in the console's **Sessions** page.

## Notes from running it

* **Posting as yourself.** With a personal token, reviews and comments are posted as your own account. GitHub does not let an author approve or request changes on their own pull request, which is why the prompt allows only `COMMENT` reviews. The marker line is how the rules tell the agent's comments from yours. A bot account's token avoids both limits.
* **Iterating on the prompt.** An agent stays on the template version it was created from, so a new template version does not change this agent's prompt; it only records the prompt for agents you create from that version later. To change the prompt of the running agent, set the agent's own system prompt (`agent.SystemPrompt.Set` in Go, `agent.system_prompt.set` in Python, `agent.systemPrompt.set` in TypeScript; see [Configuration](https://docs.paddock.build/guides/configuration.md#system-prompt)). Only sessions created afterwards use it: a pull request's existing session keeps the prompt it started with, so delete that session, or wait for the next pull request, to see the change.
* **Tools in the sandbox.** The agent reaches GitHub only through the MCP server. Say so in the prompt, so it does not reach for a CLI the sandbox does not have.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.