# 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