# review-bot

AI-powered code review bot for Gitea pull requests. Fetches diff + context, sends to an LLM, and posts a structured review (APPROVE / REQUEST_CHANGES) back to the PR.

## Features

- **Multi-provider**: OpenAI-compatible and Anthropic Messages API
- **Context-aware**: Fetches full file content, conventions, language patterns, CI status
- **Smart budget**: Automatically trims context to fit model token limits
- **Idempotent reviews**: Deletes previous review before posting new one (one review per bot)
- **Custom prompts**: Load additional instructions from a file (e.g. security-focused review)
- **Zero dependencies**: Go stdlib only

## Quick Start: Composite Action

The easiest way to use review-bot in your Gitea CI:

```yaml
# .gitea/workflows/review.yml
name: Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-24.04
    strategy:
      matrix:
        include:
          - name: code-review
            model: gpt-4.1
            token_secret: REVIEW_TOKEN
          - name: security
            model: gpt-4.1
            token_secret: REVIEW_TOKEN
            system_prompt_file: SECURITY_REVIEW.md
    steps:
      - uses: actions/checkout@v4
      - uses: https://gitea.weiker.me/rodin/review-bot/.gitea/actions/review@v0.1.0
        with:
          reviewer-token: ${{ secrets[matrix.token_secret] }}
          reviewer-name: ${{ matrix.name }}
          llm-base-url: ${{ secrets.LLM_BASE_URL }}
          llm-api-key: ${{ secrets.LLM_API_KEY }}
          llm-model: ${{ matrix.model }}
          conventions-file: CONVENTIONS.md
          system-prompt-file: ${{ matrix.system_prompt_file }}
```

## Action Inputs

| Input | Required | Default | Description |
|-------|----------|---------|-------------|
| `reviewer-token` | Yes | — | Gitea token for posting reviews (needs `write:issue`, `write:repository`) |
| `reviewer-name` | No | `""` | Logical identity for this reviewer. Used as sentinel for idempotent cleanup. Set this when running multiple review bots on the same PR. |
| `llm-base-url` | Yes | — | LLM API base URL |
| `llm-api-key` | Yes | — | LLM API key |
| `llm-model` | Yes | — | Model name |
| `llm-provider` | No | `openai` | API provider: `openai` or `anthropic` |
| `conventions-file` | No | `""` | Path to coding conventions file in the repo |
| `patterns-repo` | No | `""` | Comma-separated repos with language patterns (e.g. `rodin/go-patterns`) |
| `patterns-files` | No | `README.md` | Files/directories to fetch from pattern repos |
| `system-prompt-file` | No | `""` | Local file with additional system prompt instructions |
| `temperature` | No | `0` | LLM temperature (0 = server default) |
| `timeout` | No | `300` | LLM request timeout in seconds |
| `dry-run` | No | `false` | Print review to stdout instead of posting |
| `update-existing` | No | `true` | Delete previous review from same bot before posting. Accepts: true/1/yes or false/0/no |
| `version` | No | `latest` | review-bot version to install |

## How Review Cleanup Works

When `reviewer-name` is set, the bot embeds a hidden sentinel in each review:

```html
<!-- review-bot:code-review -->
```

On the next run, it finds and deletes any review containing its own sentinel (except the one it just posted). This means:

- **One review per bot per PR** — no clutter from repeated pushes
- **Multiple bots coexist** — each only cleans up its own reviews
- **Same token, different roles** — a single bot account can post "code-review" and "security" reviews without conflict
- **No extra permissions** — identity comes from the sentinel, not the API

If `reviewer-name` is empty, cleanup is skipped (reviews stack like before).

## Custom Review Prompts

Use `--system-prompt-file` to specialize the review focus. The file contents are appended to the base system prompt as "Additional Review Instructions."

Example `SECURITY_REVIEW.md`:

```markdown
You are performing a security-focused code review.
Focus on: injection, auth bypass, secrets exposure, input validation, race conditions.
Only report findings with security implications. Ignore style and general quality.
```

This enables running multiple specialized reviews in parallel (code quality, security, performance) from a single workflow.

## CLI Usage

```bash
review-bot \
  --gitea-url https://gitea.example.com \
  --repo owner/name \
  --pr 42 \
  --reviewer-token "$GITEA_TOKEN" \
  --reviewer-name "code-review" \
  --llm-base-url https://api.openai.com/v1 \
  --llm-api-key "$OPENAI_API_KEY" \
  --llm-model gpt-4.1 \
  --llm-provider openai \
  --conventions-file CONVENTIONS.md \
  --patterns-repo rodin/go-patterns \
  --patterns-files "README.md,patterns/" \
  --system-prompt-file SECURITY_REVIEW.md \
  --update-existing true \
  --llm-timeout 600
```

## Environment Variables

All flags have environment variable equivalents:

| Flag | Env Var |
|------|---------|
| `--gitea-url` | `GITEA_URL` |
| `--repo` | `GITEA_REPO` |
| `--pr` | `PR_NUMBER` |
| `--reviewer-token` | `REVIEWER_TOKEN` |
| `--reviewer-name` | `REVIEWER_NAME` |
| `--llm-base-url` | `LLM_BASE_URL` |
| `--llm-api-key` | `LLM_API_KEY` |
| `--llm-model` | `LLM_MODEL` |
| `--llm-provider` | `LLM_PROVIDER` |
| `--conventions-file` | `CONVENTIONS_FILE` |
| `--patterns-repo` | `PATTERNS_REPO` |
| `--patterns-files` | `PATTERNS_FILES` |
| `--system-prompt-file` | `SYSTEM_PROMPT_FILE` |
| `--llm-temperature` | `LLM_TEMPERATURE` |
| `--llm-timeout` | `LLM_TIMEOUT` |
| `--update-existing` | `UPDATE_EXISTING` |

## Setup

1. **Create a Gitea bot account** (e.g. `review-bot`)
2. **Generate a token** with scopes: `write:issue`, `write:repository`
3. **Add secrets** to your Gitea repo (Settings → Actions → Secrets):
   - `REVIEW_TOKEN` — the bot's Gitea token
   - `LLM_BASE_URL` — your LLM endpoint
   - `LLM_API_KEY` — your LLM key
4. **Add the workflow** (see Quick Start above)

### Token Scopes Required

| Scope | Purpose |
|-------|---------|
| `write:issue` | Post and delete reviews |
| `write:repository` | Read PR diffs, file content, commit statuses |

No `read:user` scope needed — the bot identifies itself from the review response.

## Development

```bash
go test ./...        # Unit tests
go vet ./...         # Static analysis
go build -o review-bot ./cmd/review-bot

# Integration tests (requires env vars set)
go test -tags=integration ./...
```

## Architecture

```
cmd/review-bot/     CLI entrypoint + orchestration
gitea/              Gitea API client (reviews, PRs, files)
llm/                Multi-provider LLM client (OpenAI + Anthropic)
review/             Prompt building, response parsing, formatting
budget/             Token estimation + context trimming
```

## License

MIT