# Workflows

This document provides ready-to-use workflow files for integrating OpenRabbit AI code review into your Gitea or GitHub repositories.

Simply copy the workflow files below into your repository's `.gitea/workflows/` or `.github/workflows/` directory.

---

## Quick Start

1. Copy the workflow files to your repository
2. Configure the required secrets (see [Required Secrets](#required-secrets))
3. Update the placeholders:
   - `YourOrg/OpenRabbit` - Your OpenRabbit fork repository
   - `https://git.example.com/api/v1` - Your Gitea instance API URL
   - `Bartender` - Your bot's username (for self-trigger prevention)

---

## Gitea Workflows

### 1. PR Review Workflow

Automatically reviews pull requests when opened or updated.

```yaml
# .gitea/workflows/enterprise-ai-review.yml
name: Enterprise AI Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  ai-review:
    runs-on: ubuntu-latest

    steps:
      # Checkout the PR repository
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      # Checkout the CENTRAL AI tooling repo
      - uses: actions/checkout@v4
        with:
          repository: YourOrg/OpenRabbit
          path: .ai-review
          token: ${{ secrets.AI_REVIEW_TOKEN }}

      # Setup Python
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      # Install dependencies
      - run: pip install requests pyyaml

      # Run the AI review
      - name: Run Enterprise AI Review
        env:
          AI_REVIEW_TOKEN: ${{ secrets.AI_REVIEW_TOKEN }}
          AI_REVIEW_REPO: ${{ gitea.repository }}
          AI_REVIEW_API_URL: https://git.example.com/api/v1
          AI_REVIEW_PR_NUMBER: ${{ gitea.event.pull_request.number }}

          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
          OLLAMA_HOST: ${{ secrets.OLLAMA_HOST }}
        run: |
          cd .ai-review/tools/ai-review
          python main.py pr ${{ gitea.repository }} ${{ gitea.event.pull_request.number }} \
            --title "${{ gitea.event.pull_request.title }}"

      # Fail CI on HIGH severity (optional)
      - name: Check Review Result
        if: failure()
        run: |
          echo "AI Review found HIGH severity issues. Please address them before merging."
          exit 1
```

---

### 2. Issue Triage Workflow

Triggers on `@codebot triage` command in issue comments.

```yaml
# .gitea/workflows/ai-issue-triage.yml
name: AI Issue Triage

# WORKFLOW ROUTING:
# This workflow handles ONLY the 'triage' command
# Other workflows: ai-comment-reply.yml (specific commands), ai-chat.yml (free-form questions)

on:
    issue_comment:
        types: [created]

jobs:
    ai-triage:
        runs-on: ubuntu-latest
        # Only run if comment contains @codebot triage
        # CRITICAL: Ignore bot's own comments to prevent infinite loops (bot username: Bartender)
        if: |
            github.event.comment.user.login != 'Bartender' &&
            contains(github.event.comment.body, '@codebot triage')
        steps:
            - uses: actions/checkout@v4

            - uses: actions/checkout@v4
              with:
                  repository: YourOrg/OpenRabbit
                  path: .ai-review
                  token: ${{ secrets.AI_REVIEW_TOKEN }}

            - uses: actions/setup-python@v5
              with:
                  python-version: "3.11"

            - run: pip install requests pyyaml

            - name: Run AI Issue Triage
              env:
                  AI_REVIEW_TOKEN: ${{ secrets.AI_REVIEW_TOKEN }}
                  AI_REVIEW_REPO: ${{ gitea.repository }}
                  AI_REVIEW_API_URL: https://git.example.com/api/v1
                  OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
                  OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
                  OLLAMA_HOST: ${{ secrets.OLLAMA_HOST }}
              run: |
                  cd .ai-review/tools/ai-review
                  python main.py issue ${{ gitea.repository }} ${{ gitea.event.issue.number }}
```

---

### 3. Comment Reply Workflow

Handles specific commands: `help`, `explain`, `suggest`, `security`, `summarize`, `changelog`, `explain-diff`, `review-again`, `setup-labels`.

```yaml
# .gitea/workflows/ai-comment-reply.yml
name: AI Comment Reply

# WORKFLOW ROUTING:
# This workflow handles SPECIFIC commands: help, explain, suggest, security, summarize, changelog, explain-diff, review-again, setup-labels
# Other workflows: ai-issue-triage.yml (@codebot triage), ai-chat.yml (free-form questions)

on:
    issue_comment:
        types: [created]

# CUSTOMIZE YOUR BOT NAME:
# Change '@codebot' in the 'if' condition below to match your config.yml mention_prefix
# Examples: '@bartender', '@uni', '@joey', '@codebot'

jobs:
    ai-reply:
        runs-on: ubuntu-latest
        # Only run for specific commands (not free-form chat or triage)
        # This prevents duplicate runs with ai-chat.yml and ai-issue-triage.yml
        # CRITICAL: Ignore bot's own comments to prevent infinite loops (bot username: Bartender)
        if: |
            github.event.comment.user.login != 'Bartender' &&
            (contains(github.event.comment.body, '@codebot help') ||
             contains(github.event.comment.body, '@codebot explain') ||
             contains(github.event.comment.body, '@codebot suggest') ||
             contains(github.event.comment.body, '@codebot security') ||
             contains(github.event.comment.body, '@codebot summarize') ||
             contains(github.event.comment.body, '@codebot changelog') ||
             contains(github.event.comment.body, '@codebot explain-diff') ||
             contains(github.event.comment.body, '@codebot review-again') ||
             contains(github.event.comment.body, '@codebot setup-labels'))
        steps:
            - uses: actions/checkout@v4

            - uses: actions/checkout@v4
              with:
                  repository: YourOrg/OpenRabbit
                  path: .ai-review
                  token: ${{ secrets.AI_REVIEW_TOKEN }}

            - uses: actions/setup-python@v5
              with:
                  python-version: "3.11"

            - run: pip install requests pyyaml

            - name: Run AI Comment Response
              env:
                  AI_REVIEW_TOKEN: ${{ secrets.AI_REVIEW_TOKEN }}
                  AI_REVIEW_API_URL: https://git.example.com/api/v1
                  OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
                  OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
                  OLLAMA_HOST: ${{ secrets.OLLAMA_HOST }}
              run: |
                  cd .ai-review/tools/ai-review

                  # Determine if this is a PR or issue comment
                  IS_PR="${{ gitea.event.issue.pull_request != null }}"
                  REPO="${{ gitea.repository }}"
                  ISSUE_NUMBER="${{ gitea.event.issue.number }}"

                  # Validate inputs
                  if [ -z "$REPO" ] || [ -z "$ISSUE_NUMBER" ]; then
                      echo "Error: Missing required parameters"
                      exit 1
                  fi

                  # Validate repository format (owner/repo)
                  if ! echo "$REPO" | grep -qE '^[a-zA-Z0-9_-]+/[a-zA-Z0-9_-]+$'; then
                      echo "Error: Invalid repository format: $REPO"
                      exit 1
                  fi

                  if [ "$IS_PR" = "true" ]; then
                      # This is a PR comment - use safe dispatch with minimal event data
                      # Build minimal event payload (does not include sensitive user data)
                      EVENT_DATA=$(cat <<EOF
                  {
                      "action": "created",
                      "issue": {
                          "number": ${{ gitea.event.issue.number }},
                          "pull_request": {}
                      },
                      "comment": {
                          "id": ${{ gitea.event.comment.id }},
                          "body": $(echo '${{ gitea.event.comment.body }}' | jq -Rs .)
                      }
                  }
                  EOF
                  )

                      # Use safe dispatch utility
                      python utils/safe_dispatch.py issue_comment "$REPO" "$EVENT_DATA"
                  else
                      # This is an issue comment - use the comment command
                      COMMENT_BODY='${{ gitea.event.comment.body }}'
                      python main.py comment "$REPO" "$ISSUE_NUMBER" "$COMMENT_BODY"
                  fi
```

---

### 4. Chat Workflow (Free-form Questions)

Handles any `@codebot` mention that isn't a specific command - for asking questions about the codebase.

```yaml
# .gitea/workflows/ai-chat.yml
name: AI Chat (Bartender)

# WORKFLOW ROUTING:
# This workflow handles FREE-FORM questions/chat (no specific command)
# Other workflows: ai-issue-triage.yml (@codebot triage), ai-comment-reply.yml (specific commands)
# This is the FALLBACK for any @codebot mention that isn't a known command

on:
    issue_comment:
        types: [created]

# CUSTOMIZE YOUR BOT NAME:
# Change '@codebot' in all conditions below to match your config.yml mention_prefix
# Examples: '@bartender', '@uni', '@joey', '@codebot'

jobs:
    ai-chat:
        # Only run if comment mentions the bot but NOT a specific command
        # This prevents duplicate runs with ai-comment-reply.yml and ai-issue-triage.yml
        # CRITICAL: Ignore bot's own comments to prevent infinite loops (bot username: Bartender)
        if: |
            github.event.comment.user.login != 'Bartender' &&
            contains(github.event.comment.body, '@codebot') &&
            !contains(github.event.comment.body, '@codebot triage') &&
            !contains(github.event.comment.body, '@codebot help') &&
            !contains(github.event.comment.body, '@codebot explain') &&
            !contains(github.event.comment.body, '@codebot suggest') &&
            !contains(github.event.comment.body, '@codebot security') &&
            !contains(github.event.comment.body, '@codebot summarize') &&
            !contains(github.event.comment.body, '@codebot changelog') &&
            !contains(github.event.comment.body, '@codebot explain-diff') &&
            !contains(github.event.comment.body, '@codebot review-again') &&
            !contains(github.event.comment.body, '@codebot setup-labels')
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v4

            - uses: actions/checkout@v4
              with:
                  repository: YourOrg/OpenRabbit
                  path: .ai-review
                  token: ${{ secrets.AI_REVIEW_TOKEN }}

            - uses: actions/setup-python@v5
              with:
                  python-version: "3.11"

            - run: pip install requests pyyaml

            - name: Run AI Chat
              env:
                  AI_REVIEW_TOKEN: ${{ secrets.AI_REVIEW_TOKEN }}
                  AI_REVIEW_REPO: ${{ gitea.repository }}
                  AI_REVIEW_API_URL: https://git.example.com/api/v1
                  OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
                  OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
                  OLLAMA_HOST: ${{ secrets.OLLAMA_HOST }}
                  SEARXNG_URL: ${{ secrets.SEARXNG_URL }}
              run: |
                  cd .ai-review/tools/ai-review
                  python main.py comment ${{ gitea.repository }} ${{ gitea.event.issue.number }} "${{ gitea.event.comment.body }}"
```

---

### 5. Codebase Analysis Workflow

Weekly scheduled codebase health analysis.

```yaml
# .gitea/workflows/ai-codebase-review.yml
name: AI Codebase Quality Review

on:
  # Weekly scheduled run
  schedule:
    - cron: "0 0 * * 0" # Every Sunday at midnight

  # Manual trigger
  workflow_dispatch:
    inputs:
      report_type:
        description: "Type of report to generate"
        required: false
        default: "full"
        type: choice
        options:
          - full
          - security
          - quick

jobs:
  ai-codebase-review:
    runs-on: ubuntu-latest

    steps:
      # Checkout the repository
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Full history for analysis

      # Checkout central AI tooling
      - uses: actions/checkout@v4
        with:
          repository: YourOrg/OpenRabbit
          path: .ai-review
          token: ${{ secrets.AI_REVIEW_TOKEN }}

      # Setup Python
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      # Install dependencies
      - run: pip install requests pyyaml

      # Run AI codebase analysis
      - name: Run AI Codebase Analysis
        env:
          AI_REVIEW_TOKEN: ${{ secrets.AI_REVIEW_TOKEN }}
          AI_REVIEW_REPO: ${{ gitea.repository }}
          AI_REVIEW_API_URL: https://git.example.com/api/v1

          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
          OLLAMA_HOST: ${{ secrets.OLLAMA_HOST }}
        run: |
          cd .ai-review/tools/ai-review
          python main.py codebase ${{ gitea.repository }}
```

---

## GitHub Workflows

For GitHub, use `${{ github.* }}` instead of `${{ gitea.* }}` and `${{ secrets.GITHUB_TOKEN }}` for authentication.

### 1. PR Review Workflow (GitHub)

```yaml
# .github/workflows/ai-review.yml
name: AI Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  ai-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - run: pip install requests pyyaml

      - name: Run AI Review
        env:
          AI_REVIEW_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          AI_REVIEW_REPO: ${{ github.repository }}
          AI_REVIEW_API_URL: https://api.github.com
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          cd tools/ai-review
          python main.py pr ${{ github.repository }} ${{ github.event.pull_request.number }}
```

### 2. Issue Triage Workflow (GitHub)

```yaml
# .github/workflows/ai-issue-triage.yml
name: AI Issue Triage

on:
  issue_comment:
    types: [created]

jobs:
  ai-triage:
    runs-on: ubuntu-latest
    # CRITICAL: Update 'YourBotUsername' to your bot's actual GitHub username
    if: |
      github.event.comment.user.login != 'YourBotUsername' &&
      contains(github.event.comment.body, '@codebot triage')
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - run: pip install requests pyyaml

      - name: Run AI Issue Triage
        env:
          AI_REVIEW_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          AI_REVIEW_REPO: ${{ github.repository }}
          AI_REVIEW_API_URL: https://api.github.com
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          cd tools/ai-review
          python main.py issue ${{ github.repository }} ${{ github.event.issue.number }}
```

### 3. Comment Reply Workflow (GitHub)

```yaml
# .github/workflows/ai-comment-reply.yml
name: AI Comment Reply

on:
  issue_comment:
    types: [created]

jobs:
  ai-reply:
    runs-on: ubuntu-latest
    # CRITICAL: Update 'YourBotUsername' to your bot's actual GitHub username
    if: |
      github.event.comment.user.login != 'YourBotUsername' &&
      (contains(github.event.comment.body, '@codebot help') ||
       contains(github.event.comment.body, '@codebot explain') ||
       contains(github.event.comment.body, '@codebot suggest') ||
       contains(github.event.comment.body, '@codebot security') ||
       contains(github.event.comment.body, '@codebot summarize') ||
       contains(github.event.comment.body, '@codebot changelog') ||
       contains(github.event.comment.body, '@codebot explain-diff') ||
       contains(github.event.comment.body, '@codebot review-again') ||
       contains(github.event.comment.body, '@codebot setup-labels'))
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - run: pip install requests pyyaml

      - name: Run AI Comment Response
        env:
          AI_REVIEW_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          AI_REVIEW_REPO: ${{ github.repository }}
          AI_REVIEW_API_URL: https://api.github.com
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          SEARXNG_URL: ${{ secrets.SEARXNG_URL }}
        run: |
          cd tools/ai-review
          python main.py comment ${{ github.repository }} ${{ github.event.issue.number }} "${{ github.event.comment.body }}"
```

### 4. Chat Workflow (GitHub)

```yaml
# .github/workflows/ai-chat.yml
name: AI Chat

on:
  issue_comment:
    types: [created]

jobs:
  ai-chat:
    runs-on: ubuntu-latest
    # CRITICAL: Update 'YourBotUsername' to your bot's actual GitHub username
    if: |
      github.event.comment.user.login != 'YourBotUsername' &&
      contains(github.event.comment.body, '@codebot') &&
      !contains(github.event.comment.body, '@codebot triage') &&
      !contains(github.event.comment.body, '@codebot help') &&
      !contains(github.event.comment.body, '@codebot explain') &&
      !contains(github.event.comment.body, '@codebot suggest') &&
      !contains(github.event.comment.body, '@codebot security') &&
      !contains(github.event.comment.body, '@codebot summarize') &&
      !contains(github.event.comment.body, '@codebot changelog') &&
      !contains(github.event.comment.body, '@codebot explain-diff') &&
      !contains(github.event.comment.body, '@codebot review-again') &&
      !contains(github.event.comment.body, '@codebot setup-labels')
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - run: pip install requests pyyaml

      - name: Run AI Chat
        env:
          AI_REVIEW_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          AI_REVIEW_REPO: ${{ github.repository }}
          AI_REVIEW_API_URL: https://api.github.com
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          SEARXNG_URL: ${{ secrets.SEARXNG_URL }}
        run: |
          cd tools/ai-review
          python main.py comment ${{ github.repository }} ${{ github.event.issue.number }} "${{ github.event.comment.body }}"
```

### 5. Codebase Analysis Workflow (GitHub)

```yaml
# .github/workflows/ai-codebase-review.yml
name: AI Codebase Analysis

on:
  schedule:
    - cron: "0 0 * * 0"  # Weekly on Sunday
  workflow_dispatch:

jobs:
  ai-codebase:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - run: pip install requests pyyaml

      - name: Run Codebase Analysis
        env:
          AI_REVIEW_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          AI_REVIEW_REPO: ${{ github.repository }}
          AI_REVIEW_API_URL: https://api.github.com
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          cd tools/ai-review
          python main.py codebase ${{ github.repository }}
```

---

## Required Secrets

### Gitea

| Secret | Required | Description |
|--------|----------|-------------|
| `AI_REVIEW_TOKEN` | Yes | Gitea bot access token with repo read/write |
| `OPENAI_API_KEY` | Choose one | OpenAI API key |
| `OPENROUTER_API_KEY` | Choose one | OpenRouter API key |
| `OLLAMA_HOST` | Choose one | Ollama server URL (e.g., `http://localhost:11434`) |
| `SEARXNG_URL` | Optional | SearXNG instance for web search |

### GitHub

| Secret | Required | Description |
|--------|----------|-------------|
| `GITHUB_TOKEN` | Auto | Built-in token (automatic) |
| `OPENAI_API_KEY` | Choose one | OpenAI API key |
| `OPENROUTER_API_KEY` | Choose one | OpenRouter API key |
| `OLLAMA_HOST` | Choose one | Ollama server URL |
| `SEARXNG_URL` | Optional | SearXNG instance for web search |

---

## Customization Guide

### Changing the Bot Name

1. Update `config.yml`:
   ```yaml
   interaction:
     mention_prefix: "@yourbot"
   ```

2. Update all workflow files - replace `@codebot` with your bot name

3. Update the bot username check - replace `'Bartender'` with your bot's username

### Using a Different LLM Provider

Set the appropriate secret and update `config.yml`:

```yaml
# For OpenRouter (Claude, etc.)
provider: openrouter
model:
  openrouter: anthropic/claude-3.5-sonnet

# For Ollama (self-hosted)
provider: ollama
model:
  ollama: codellama:13b
```

### Disabling Specific Features

In `config.yml`:

```yaml
agents:
  pr:
    enabled: true
    security_scan: true      # Set to false to disable security scanning
    inline_comments: true    # Set to false to disable inline comments
    auto_summary:
      enabled: true          # Set to false to disable auto-summary for empty PRs
  
  issue:
    enabled: true
    auto_label: true         # Set to false to disable auto-labeling
```

---

## Workflow Routing Logic

The workflows are designed to be **mutually exclusive** to prevent duplicate runs:

```
@codebot mention detected
├── Contains "triage"?
│   └── YES → ai-issue-triage.yml
├── Contains specific command (help, explain, suggest, etc.)?
│   └── YES → ai-comment-reply.yml
└── Just @codebot + question (no command)?
    └── YES → ai-chat.yml
```

**Important:** All workflows include a check to ignore the bot's own comments, preventing infinite loops.

---

## Troubleshooting

### Duplicate Workflow Runs

If you see multiple workflows triggering:
1. Check that command conditions in ai-chat.yml exclude all commands from ai-comment-reply.yml
2. Verify the bot username check is correct

### Bot Not Responding

1. Check that secrets are configured correctly
2. Verify the API URL is correct for your platform
3. Check workflow logs for errors

### Infinite Loop Prevention

All workflows include:
```yaml
if: github.event.comment.user.login != 'BotUsername'
```

Make sure to update `'BotUsername'` to your actual bot's login name.

---

## Example Usage

After setting up the workflows:

```
# Triage an issue
@codebot triage

# Get help
@codebot help

# Ask a question about the codebase
@codebot how does authentication work?

# Generate PR summary
@codebot summarize

# Generate changelog
@codebot changelog

# Re-run PR review
@codebot review-again

# Setup repository labels
@codebot setup-labels
```