openrabbit/INSTALL.md

Installation

Add OpenRabbit AI code review to your Gitea or GitHub repository in under 5 minutes.

---

Quick Start (Recommended)

Automated Setup

Run the interactive setup wizard:

# Clone OpenRabbit (or download setup.sh)
git clone https://github.com/YourOrg/openrabbit.git
cd openrabbit

# Run setup wizard
./setup.sh

The wizard will:

• ✅ Ask for your platform (Gitea/GitHub)
• ✅ Configure bot name and LLM provider
• ✅ Generate workflow files for your platform
• ✅ Create basic configuration file
• ✅ Provide step-by-step next actions

That's it! Follow the wizard's output to complete setup.

---

Prerequisites

Before you start, ensure you have:

• Gitea or GitHub repository with Actions enabled
• Python 3.11+ (for the AI review tools)
• LLM API access - Choose one:
  • OpenAI API key (recommended for getting started)
  • Anthropic Claude API key
  • Azure OpenAI Service access
  • Google Gemini API key
  • Self-hosted Ollama instance
• Bot account (for Gitea) or use built-in GITHUB_TOKEN (for GitHub)

---

Manual Setup

Prefer to set up manually? Follow these platform-specific instructions.

For Gitea

1. Create Bot Account

1. Create a new Gitea user (e.g., codebot, ai-reviewer)
2. Generate an access token:
   • Go to User Settings → Applications → Generate New Token
   • Enable scopes: repo (Full repository access), issue (Issue read/write)
3. Save the token securely

2. Add Organization/Repository Secrets

Go to Settings → Secrets and add:

Secret Name	Description	Required
AI_REVIEW_TOKEN	Bot's Gitea access token	✅ Yes
OPENAI_API_KEY	OpenAI API key (or your LLM provider's key)	✅ Yes
OPENROUTER_API_KEY	OpenRouter API key	Only if using OpenRouter
OLLAMA_HOST	Ollama server URL (e.g., http://localhost:11434)	Only if using Ollama
SEARXNG_URL	SearXNG instance URL for web search	Optional

3. Add Workflow Files

Copy workflow files to your repository:

# In your project repository
mkdir -p .gitea/workflows

# Copy from OpenRabbit (adjust path as needed)
cp /path/to/openrabbit/templates/workflows/*.yml .gitea/workflows/

# Edit each workflow file and replace:
# - {{OPENRABBIT_REPO}} → Your OpenRabbit fork (e.g., YourOrg/openrabbit)
# - {{API_URL}} → Your Gitea API URL (e.g., https://gitea.example.com/api/v1)
# - {{BOT_NAME}} → Your bot mention name (e.g., codebot)
# - {{BOT_USERNAME}} → Your bot account username
# - {{PLATFORM}} → gitea

Or use the setup wizard to generate them automatically: ./setup.sh

4. Commit and Push

git add .gitea/workflows/
git commit -m "Add OpenRabbit AI code review"
git push

5. Set Up Labels

Create an issue and comment:

@codebot setup-labels

The bot will automatically create required labels.

---

For GitHub

1. Add Repository/Organization Secrets

Go to Settings → Secrets and variables → Actions:

Secret Name	Description	Required
OPENAI_API_KEY	OpenAI API key (or your LLM provider's key)	✅ Yes
AI_REVIEW_TOKEN	Only if OpenRabbit repo is private	Optional
OPENROUTER_API_KEY	OpenRouter API key	Only if using OpenRouter
OLLAMA_HOST	Ollama server URL	Only if using Ollama
SEARXNG_URL	SearXNG instance URL	Optional

Note: GitHub's built-in GITHUB_TOKEN is used automatically for API access.

2. Add Workflow Files

Copy workflow files to your repository:

# In your project repository
mkdir -p .github/workflows

# Copy from OpenRabbit
cp /path/to/openrabbit/templates/workflows/*.yml .github/workflows/

# Edit each workflow file and replace:
# - {{OPENRABBIT_REPO}} → OpenRabbit repository (e.g., anthropics/openrabbit)
# - {{API_URL}} → https://api.github.com
# - {{BOT_NAME}} → Your bot mention name (e.g., codebot)
# - {{BOT_USERNAME}} → Your bot username (or 'github-actions[bot]')
# - {{PLATFORM}} → github

Or use the setup wizard: ./setup.sh

3. Commit and Push

git add .github/workflows/
git commit -m "Add OpenRabbit AI code review"
git push

4. Set Up Labels

Create an issue and comment:

@codebot setup-labels

---

Configuration

Basic Configuration

If you used the setup wizard, a basic tools/ai-review/config.yml was created.

Advanced Configuration

For advanced settings, see:

• Configuration Reference - All config options
• Agent Documentation - Agent-specific settings
• LLM Providers - Provider setup

Per-Repository Overrides

Create .ai-review.yml in your project root to override settings:

# .ai-review.yml
review:
  fail_on_severity: MEDIUM  # Override: fail on MEDIUM instead of HIGH

agents:
  pr:
    auto_summary:
      enabled: false  # Disable auto-summary for this repo

---

Testing Your Setup

Test PR Review

1. Create a new pull request
2. Wait 30-60 seconds for the workflow to run
3. Check for the AI review comment with inline suggestions

Test Issue Triage

1. Create a new issue
2. Comment: @codebot triage
3. The bot should analyze and label the issue

Test Chat

1. On any issue, comment: @codebot How does authentication work?
2. The bot should search the codebase and respond

Test Commands

Try these commands in issue comments:

• @codebot help - Show all available commands
• @codebot explain - Explain the issue in detail
• @codebot summarize - Generate a summary
• @codebot suggest - Get solution suggestions

---

Troubleshooting

Workflow Not Triggering

Problem: No AI review appears after creating a PR.

Solutions:

• ✅ Verify Actions/Workflows are enabled in repository settings
• ✅ Check workflow files are in correct directory (.gitea/workflows/ or .github/workflows/)
• ✅ Review workflow syntax: cat .gitea/workflows/enterprise-ai-review.yml
• ✅ Check Actions tab for error logs

"Missing Token" Error

Problem: Workflow fails with authentication error.

Solutions:

• ✅ Verify AI_REVIEW_TOKEN secret is set (Gitea)
• ✅ Verify token has correct permissions: repo, issue
• ✅ For private OpenRabbit repos on GitHub, set AI_REVIEW_TOKEN

"LLM Call Failed" Error

Problem: Workflow fails when calling the LLM.

Solutions:

• ✅ Verify API key secret is set (OPENAI_API_KEY, etc.)
• ✅ Check API key is valid and has credits/quota remaining
• ✅ Verify provider in config.yml matches your secret
• ✅ For Ollama: verify OLLAMA_HOST is accessible from runner

Bot Not Responding to Commands

Problem: Commenting @codebot help does nothing.

Solutions:

• ✅ Verify bot name matches mention_prefix in config.yml
• ✅ Check bot username in workflow if: conditions matches actual bot account
• ✅ Verify github.event.comment.user.login != 'BotUsername' in workflows (prevents infinite loops)
• ✅ Check Actions tab to see if workflow ran

Labels Not Applied

Problem: Bot reviews the code but doesn't add labels.

Solutions:

• ✅ Run @codebot setup-labels to create required labels
• ✅ Verify bot account has permission to manage labels
• ✅ Check label names in config.yml match repository labels

Need More Help?

• Troubleshooting Guide - Comprehensive troubleshooting
• Getting Started - Detailed setup walkthrough
• GitHub Issues - Report bugs or ask questions

---

Next Steps

Once OpenRabbit is working:

Customize Behavior

• Configuration Guide - Adjust review settings, severity thresholds
• Agent Reference - Enable/disable agents, configure features
• Security Scanning - Understand security rules, add custom rules

Enterprise Features

• Notifications - Slack/Discord alerts
• Metrics - Prometheus monitoring
• Audit Logging - Compliance and audit trails
• CODEOWNERS - Enforce code ownership

Advanced Usage

• Workflow Reference - Understand workflow routing
• CLI Usage - Run reviews locally
• API Reference - Integrate with custom tools

---

Support

• Documentation: docs/
• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

🎉 Enjoy automated code reviews with OpenRabbit!