first commit

2025-12-21 13:42:30 +01:00
parent 823b825acb
commit f9b24fe248
47 changed files with 8222 additions and 1 deletions
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -0,0 +1,142 @@
+# 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:
+
+```bash
+# 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, @ai-bot | 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 @ai-bot Commands:
+1. On any issue, comment: `@ai-bot 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](troubleshooting.md) 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:
+
+```bash
+# Review a pull request
+python main.py pr owner/repo 123
+
+# Triage a new issue
+python main.py issue owner/repo 456
+
+# Handle @ai-bot command in comment
+python main.py comment owner/repo 456 "@ai-bot summarize"
+
+# Analyze codebase
+python main.py codebase owner/repo
+```
+
+---
+
+## Next Steps
+
+- [Configuration Reference](configuration.md) - Customize behavior
+- [Agents Documentation](agents.md) - Learn about each agent
+- [Security Scanning](security.md) - Understand security rules