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:

```bash
# 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:

```bash
# 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

```bash
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:

```bash
# 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

```bash
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](docs/configuration.md)** - All config options
- **[Agent Documentation](docs/agents.md)** - Agent-specific settings
- **[LLM Providers](docs/configuration.md#llm-providers)** - Provider setup

### Per-Repository Overrides

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

```yaml
# .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](docs/troubleshooting.md)** - Comprehensive troubleshooting
- **[Getting Started](docs/getting-started.md)** - Detailed setup walkthrough
- **[GitHub Issues](https://github.com/YourOrg/openrabbit/issues)** - Report bugs or ask questions

---

## Next Steps

Once OpenRabbit is working:

### Customize Behavior
- **[Configuration Guide](docs/configuration.md)** - Adjust review settings, severity thresholds
- **[Agent Reference](docs/agents.md)** - Enable/disable agents, configure features
- **[Security Scanning](docs/SECURITY.md)** - Understand security rules, add custom rules

### Enterprise Features
- **[Notifications](docs/enterprise.md#notifications)** - Slack/Discord alerts
- **[Metrics](docs/enterprise.md#metrics)** - Prometheus monitoring
- **[Audit Logging](docs/enterprise.md#audit-trail)** - Compliance and audit trails
- **[CODEOWNERS](docs/enterprise.md#codeowners)** - Enforce code ownership

### Advanced Usage
- **[Workflow Reference](docs/workflows.md)** - Understand workflow routing
- **[CLI Usage](docs/getting-started.md#helper-cli-usage)** - Run reviews locally
- **[API Reference](docs/api-reference.md)** - Integrate with custom tools

---

## Support

- **Documentation:** [docs/](docs/)
- **Issues:** [GitHub Issues](https://github.com/YourOrg/openrabbit/issues)
- **Discussions:** [GitHub Discussions](https://github.com/YourOrg/openrabbit/discussions)

---

**🎉 Enjoy automated code reviews with OpenRabbit!**