openrabbit/docs/getting-started.md

Getting Started

This guide will help you set up the AI Code Review system for your Gitea repositories.

Prerequisites

• Gitea instance (self-hosted or managed)
• Python 3.11+
• LLM API access (OpenAI, OpenRouter, or Ollama)

---

Step 1: Create a Bot Account

1. Create a new Gitea user account for the bot (e.g., ai-reviewer)
2. Generate an access token with these permissions:
   • repo - Full repository access
   • issue - Issue read/write access
3. Save the token securely

---

Step 2: Configure Organization Secrets

In your Gitea organization or repository settings, add these secrets:

Secret	Description
AI_REVIEW_TOKEN	Bot's Gitea access token
OPENAI_API_KEY	OpenAI API key (if using OpenAI)
OPENROUTER_API_KEY	OpenRouter key (if using OpenRouter)
OLLAMA_HOST	Ollama URL (if using Ollama, e.g., http://localhost:11434)

---

Step 3: Add Workflows to Your Repository

Copy the workflow files from this repository to your target repo:

# Create workflows directory
mkdir -p .gitea/workflows

# Copy workflow files
# Option 1: Copy manually from this repo's .gitea/workflows/
# Option 2: Reference this repo in your workflows (see README)

Workflow Files:

File	Trigger	Purpose
enterprise-ai-review.yml	PR opened/updated	Run AI code review
ai-issue-review.yml	Issue opened, @codebot	Triage issues & respond to commands
ai-codebase-review.yml	Weekly/manual	Analyze codebase health

---

Step 4: Create Labels

Create these labels in your repository for auto-labeling:

Priority Labels:

• priority: high (red)
• priority: medium (yellow)
• priority: low (green)

Type Labels:

• type: bug
• type: feature
• type: question
• type: documentation

AI Status Labels:

• ai-approved
• ai-changes-required
• ai-reviewed

---

Step 5: Test the Setup

Test PR Review:

1. Create a new pull request
2. Wait for the AI review workflow to run
3. Check for the AI review comment

Test Issue Triage:

1. Create a new issue
2. The AI should automatically triage and comment

Test @codebot Commands:

1. On any issue, comment: @codebot summarize
2. The AI should respond with a summary

---

Troubleshooting

Common Issues:

"Missing token" error:

• Verify AI_REVIEW_TOKEN is set in secrets
• Ensure the token has correct permissions

"LLM call failed" error:

• Verify your LLM API key is set
• Check the provider setting in config.yml

Workflow not triggering:

• Verify workflow files are in .gitea/workflows/
• Check that Actions are enabled for your repository

See Troubleshooting Guide for more.

---

Helper: CLI Usage

If you need to run the agents manually (e.g. for debugging or local testing), you can use the CLI:

# Review a pull request
python main.py pr owner/repo 123

# Triage a new issue
python main.py issue owner/repo 456

# Handle @codebot command in comment
python main.py comment owner/repo 456 "@codebot summarize"

# Analyze codebase
python main.py codebase owner/repo

---

Next Steps

• Configuration Reference - Customize behavior
• Agents Documentation - Learn about each agent
• Security Scanning - Understand security rules