92 lines
3.4 KiB
Markdown
92 lines
3.4 KiB
Markdown
# Herald
|
|
|
|
Herald is a Gitea bot that performs automated AI-powered code reviews on pull requests using [OpenRouter](https://openrouter.ai/).
|
|
|
|
## Features
|
|
|
|
- Listens for Gitea webhook events and triggers code reviews on pull request comments
|
|
- Streams reviews back to Gitea as PR comments
|
|
- Concurrent review processing with configurable parallelism
|
|
- Graceful shutdown — in-progress reviews finish before the process exits
|
|
- Error tracking via Sentry
|
|
- Prometheus metrics endpoint for monitoring
|
|
- Tiny memory footprint (~4MB) thanks to Rust
|
|
|
|
## Installation
|
|
|
|
**Requirements:** Rust toolchain ([rustup.rs](https://rustup.rs))
|
|
|
|
```sh
|
|
cargo build --release
|
|
./target/release/herald
|
|
```
|
|
|
|
Herald reads its configuration from environment variables (a `.env` file is supported):
|
|
|
|
| Variable | Description |
|
|
|---|---|
|
|
| `HTTP_PORT` | Port to listen on |
|
|
| `BOT_NAME` | The bot's Gitea username (used to detect mentions) |
|
|
| `WEBHOOK_SIG_HEADER_SECRET` | Gitea webhook secret for signature verification |
|
|
| `OPEN_ROUTER_API_KEY` | OpenRouter API key |
|
|
| `OPEN_ROUTER_MODEL` | Model to use (e.g. `deepseek/deepseek-v4-flash`) |
|
|
| `OPEN_ROUTER_TIMEOUT` | OpenRouter request timeout in seconds |
|
|
| `BOT_MAX_CONCURRENT` | Maximum number of concurrent reviews |
|
|
| `GITEA_URL` | Base URL of your Gitea instance |
|
|
| `GITEA_TOKEN` | Gitea API token |
|
|
| `GITEA_TIMEOUT` | Gitea API request timeout in seconds |
|
|
| `METRICS_BIND_ADDR` | *(optional)* Bind address for the Prometheus metrics endpoint (e.g. `0.0.0.0:9100`). If unset, the metrics exporter is disabled. |
|
|
| `SENTRY_DSN` | *(optional)* Sentry DSN for error tracking |
|
|
| `RUST_LOG` | *(optional)* Log level, defaults to `info` |
|
|
|
|
## Development
|
|
|
|
The easiest way to get started is with the provided [Dev Container](https://containers.dev/) (VS Code or Zed with the dev container extension).
|
|
|
|
Open the project and reopen it in the container — the Rust toolchain is pre-installed.
|
|
|
|
**Without Dev Container**, you just need a Rust toolchain:
|
|
|
|
```sh
|
|
rustup toolchain install stable
|
|
cargo run
|
|
```
|
|
|
|
Copy `.env.example` to `.env` and fill in your values before running.
|
|
|
|
## Metrics
|
|
|
|
Herald optionally exposes a Prometheus metrics endpoint, useful for scraping with an [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/) or any Prometheus-compatible scraper.
|
|
|
|
Set `METRICS_BIND_ADDR` (e.g. `0.0.0.0:9100`) to enable it. The metrics are then available at `http://<host>:9100/metrics`.
|
|
|
|
### Exposed metrics
|
|
|
|
| Metric | Type | Description |
|
|
|---|---|---|
|
|
| `herald_webhooks_received_total` | counter | Total webhooks received (label: `event_type`) |
|
|
| `herald_webhooks_duplicate_total` | counter | Webhooks rejected as duplicates (label: `event_type`) |
|
|
| `herald_webhooks_channel_full_total` | counter | Webhooks dropped because the bot channel was full (label: `event_type`) |
|
|
| `herald_bot_tasks_active` | gauge | Bot tasks currently in progress |
|
|
| `herald_bot_tasks_completed_total` | counter | Bot tasks completed successfully (label: `event_type`) |
|
|
| `herald_bot_tasks_failed_total` | counter | Bot tasks that failed (label: `event_type`) |
|
|
| `herald_openrouter_cost_cents_total` | counter | Total OpenRouter cost in cents (divide by 100 for USD) |
|
|
|
|
### OTel collector example
|
|
|
|
```yaml
|
|
receivers:
|
|
prometheus:
|
|
config:
|
|
scrape_configs:
|
|
- job_name: herald
|
|
scrape_interval: 15s
|
|
static_configs:
|
|
- targets: ["herald:9100"]
|
|
|
|
service:
|
|
pipelines:
|
|
metrics:
|
|
receivers: [prometheus]
|
|
exporters: [otlp]
|
|
``` |