Add automated setup system for easy installation
All checks were successful
AI Codebase Quality Review / ai-codebase-review (push) Successful in 36s
All checks were successful
AI Codebase Quality Review / ai-codebase-review (push) Successful in 36s
- Add setup.sh interactive wizard for 5-minute setup - Add INSTALL.md comprehensive installation guide - Add templates/workflows/ directory with parameterized workflow templates - Update README.md with prominent Installation section - Update docs/README.md with installation links The setup wizard automates: - Platform selection (Gitea/GitHub) - Bot configuration - LLM provider setup - Workflow file generation - Configuration file creation Users can now add OpenRabbit to any repository in under 5 minutes. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
318
INSTALL.md
Normal file
318
INSTALL.md
Normal file
@@ -0,0 +1,318 @@
|
||||
# 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!**
|
||||
Reference in New Issue
Block a user