Probatus

Probatus is a web UI application that streamlines RFC and ADR (Architecture Decision Record) review and approval workflows, integrated with GitHub and Codeberg (Forgejo).

It provides a clear, structured view of document lifecycles — who approved what, when, and why — while keeping your Git repository as the source of truth.

Caution

This project is in early development and is being built with heavy use of AI-assisted coding to move fast. Code quality, test coverage, and security hardening are not yet at production standards. Do not use in production. Expect breaking changes, rough edges, and incomplete error handling. Contributions and bug reports are welcome — just be aware of the current state.

Features

• Stage-based lifecycle management: Draft → Proposed → Under Review → Accepted → Implemented → Superseded/Deprecated, with Rejected branching
• Approval tracking: N/M approval rules with full audit trail (who approved, when, with comments)
• Multi-repository dashboard: Cross-repository view of all RFCs and ADRs in one place
• Git synchronization: PR labels and bot comments keep GitHub/Codeberg in sync with Probatus state
• MCP Server: AI agents (Claude Code, etc.) can query and manage RFCs/ADRs via Model Context Protocol
• CI Actions: Validation, stage sync, and approval gate actions for GitHub/Forgejo Actions
• Structured discussions: Topic-based discussion threads with section-level comments, separate from PR comments

Quick Start

Binary

# Download the latest release
curl -LO https://codeberg.org/nxeu/probatus/releases/latest/download/probatus-$(uname -s)-$(uname -m)
chmod +x probatus-*
./probatus-* init # Generate default config
./probatus-* serve

Docker

docker run -d \
 -p 3000:3000 \
 -v probatus-data:/data \
 -e PROBATUS__AUTH__GITHUB__CLIENT_ID=your_client_id \
 -e PROBATUS__AUTH__GITHUB__CLIENT_SECRET=your_client_secret \
 codeberg.org/nxeu/probatus:latest

Configuration

Probatus is configured via probatus-server.toml with environment variable overrides.

[server]
host = "0.0.0.0"
port = 3000
base_url = "https://probatus.example.com"
[database]
path = "./data/probatus.db"
[auth.github]
client_id = ""
client_secret = ""
[webhook]
secret = ""
[sync]
polling_interval = "5m"

Environment variables follow the pattern PROBATUS__{SECTION}__{KEY} (e.g., PROBATUS__SERVER__PORT=8080).

Repository Setup

Add a .probatus.toml to your repository root to configure RFC/ADR detection:

[documents]
rfc_paths = ["docs/rfcs"]
adr_paths = ["docs/adrs"]
pattern = "*.md"
[approval]
required_approvals = 2

Without .probatus.toml, Probatus scans default paths: docs/rfcs/, docs/adrs/, rfcs/, adrs/.

RFC/ADR Format

Probatus expects Markdown files with YAML frontmatter:

---
title: Use event sourcing for audit trail
status: draft
authors: ["@username"]
created: 2026年01月15日
tags: ["architecture", "backend"]
related: ["docs/adrs/001-database-choice.md"]
---
## Context

...
## Decision

...
## Consequences

...

Required fields

• title — Document title
• status — Current stage (draft, proposed, under_review, accepted, implemented, superseded, deprecated, rejected)
• authors — List of authors
• created — Creation date

Recommended fields

• reviewers — List of reviewers
• tags — Classification tags
• related — Related RFC/ADR paths
• supersedes / superseded_by — Replacement relationships

MCP Server

The MCP server is a standalone binary that lets AI agents interact with your RFCs/ADRs.

Standalone mode (no Probatus server required)

{
 "mcpServers": {
 "probatus": {
 "command": "probatus-mcp",
 "env": {
 "GITHUB_TOKEN": "ghp_..."
 }
 }
 }
}

Connected mode (with Probatus server)

{
 "mcpServers": {
 "probatus": {
 "command": "probatus-mcp",
 "env": {
 "PROBATUS_URL": "https://probatus.example.com",
 "PROBATUS_TOKEN": "..."
 }
 }
 }
}

Available tools

GitHub/Forgejo Actions

Stage Sync

- uses:nxeu/probatus/actions/sync@v0with:probatus-url:${{ secrets.PROBATUS_URL }} # optionalprobatus-token:${{ secrets.PROBATUS_TOKEN }} # optional

Validation

- uses:nxeu/probatus/actions/validate@v0with:strict:false# Set true to error on missing recommended sections

Approval Gate

- uses:nxeu/probatus/actions/gate@v0with:probatus-url:${{ secrets.PROBATUS_URL }}probatus-token:${{ secrets.PROBATUS_TOKEN }}required-stage:accepted

Tech Stack

• Backend: Rust / Axum
• Frontend: Vite + React + shadcn/ui + Tailwind CSS + TanStack Query
• Database: SQLite (sqlx, FTS5)
• API: REST + OpenAPI 3.1
• MCP: Rust (stdio transport)
• Auth: GitHub / Forgejo OAuth 2.0
• License: AGPL-3.0

Development

# Prerequisites: Rust toolchain, Node.js 22+, pnpm, vp (vite-plus)
git clone https://codeberg.org/nxeu/probatus.git
cd probatus
# Backend
cargo build
# Frontend
cd web && pnpm install && vp dev
# Run tests
cargo test

License

This project is licensed under the GNU Affero General Public License v3.0.