kodo/reviewer
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Added docs folder

Browse Source
This commit is contained in:
Alexey Efimchik
2026-03-12 12:03:22 +07:00
parent 2fb6c77f5f
commit 4a59c2fd4f
8 changed files with 390 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

101
docs/develoepr-guide/ai-reviewer-output-format.md Normal file
View File

@@ -0,0 +1,101 @@
# AI Code Reviewer — Output Comment Format
## 1. Summary Comment
The summary comment is posted by the bot as a **top-level PR comment** after the review is complete.
It provides a high-level assessment of the entire diff.
### Format
```
🔴 Code quality assessment: <Poor | Acceptable | Excellent>
ℹ️ Conclusion: <Short explanation of the most critical finding and its impact>
❌ Merge: No - <reason>
✅ Merge: Yes
```
### Example
> 🔴 Code quality assessment: Poor
>
> ℹ️ Conclusion: The commit introduces a critical bug where `Stopwatch.StartNew()` is called twice on consecutive lines (lines 15–16 in `samples/AR/App.cs`). The duplicate assignment statement must be removed.
>
> ❌ Merge: No - blocking issue must be resolved first
### Quality Levels
| Badge | Label | Meaning |
|---|---|---|
| 🔴 | Poor | Blocking issues found, must not merge |
| 🟡 | Acceptable | Minor suggestions only |
| ✅ | Excellent | No issues found |
---
## 2. Inline Comments
Inline comments are posted **directly on the changed lines** in the diff.
They follow the [**Conventional Comments**](https://conventionalcomments.org/) approach to make severity and intent immediately clear.
### Conventional Comments Format
```
<emoji> <label> (<optional decoration>): <subject>
<body — explanation of the issue>
💻 Suggested Code:
<code block with the fix>
```
### Example
Posted inline on line 16 of `samples/AR/App.cs`:
---
> 🔴 Issue (Blocking): Duplicate Stopwatch initialization
>
> The `Stopwatch.StartNew()` call on line 15 is repeated on line 16, which overwrites the first instance. This appears to be an accidental duplicate that should be removed.
>
> 💻 Suggested Code:
> ```csharp
> public void Run(string reportName, Dictionary<string, object[]>? reportParameters)
> {
> var sw = Stopwatch.StartNew();
> Trace.WriteLine($"{sw.ElapsedMilliseconds} : Start { reportName}!");
> _reportExport.Run(reportName, reportParameters, sw);
> sw.Stop();
> Trace.WriteLine($"{sw.ElapsedMilliseconds} : End!");
> }
> ```
## 3. Request Changes or Approve Pull Request
After posting comments, the bot submits a **formal PR review** with one of two states.
### Request Changes
Triggered when one or more **Blocking** issues are found.
```
Status: ❌ Request Changes
```
The PR is blocked from merging (if branch protection rules are enabled) until:
- The author fixes the blocking issues
- The bot re-reviews after a new commit (`synchronize` event)
- A human reviewer overrides the block
---
### Approved
Triggered when no blocking issues are found.
```
Status: ✅ Approved
```

41
docs/develoepr-guide/extension-of-rules.md Normal file
View File

@@ -0,0 +1,41 @@
# Review Prompt Extension
The Kodo tool supports the ability to extend the built-in prompt for review. This can be done in the following way
## 1. The CONSTITUTION.md file
You can create a `.review` folder if it does not exist and add a `CONSTITUTION.md` file to this folder, which will contain part of the prompt that will be read by the tool during execution.
```
my-project/
├── .review/ ← Create this folder
│ └── CONSTITUTION.md ← Your custom rules
├── src/
└── ...
```
The `.review` folder must be placed in the **root of your repository**.
### 1.1. Example of the CONSTITUTION.md file.
Example of a file you can create
``` markdown
# Additional rules for code reviews.
1. Do not check dependency declarations in code files
2. Do not check namespaces
# Knowledge about the project structure
This project contains the following modules:
1. DataEngine - the core for processing user data.
2. Viewer - a tool for visualizing user data.
```
### 1.2. Recommendations for the CONSTITUTION.md file
There are some recommendations for creating content for this file:
1. Do not provide contradictory instructions and information.
2. Provide a detailed description of any modules and rules.
3. Do not make this file large, as it will be part of the prompt, which has a limited context.

46
docs/develoepr-guide/faq-troubleshooting.md Normal file
View File

@@ -0,0 +1,46 @@
# AI Code Reviewer — Troubleshooting: Reviewer Did Not Run
## Quick Checklist
Before diving deeper, verify the basics:
- The workflow file exists at `.gitea/workflows/kodo-reviewer.yaml`
- Secrets `CC_GITEATOKEN` and `CC_API_KEY` are set in repository settings
- The runner `kodo-review` is online and available
- The PR title does **not** contain `[no ai]`
- The event that triggered the workflow matches one of the configured triggers
---
## Common Causes & Fixes
### 1. Secrets are missing or misconfigured
If `CC_GITEATOKEN` or `CC_API_KEY` are not set, the action will fail silently or error out.
**How to check:**
1. Go to repository **Settings → Secrets**
2. Verify both secrets exist:
- `CC_GITEATOKEN` — Gitea token with read/write access to PRs
- `CC_API_KEY` — Anthropic API key
**Fix:** Add/regenerate missing secrets or contact with `devops` team.
---
### 2. PR title contains `[no ai]`
The action checks for `[no ai]` in the PR title and skips execution if found.
**Fix:** Remove `[no ai]` from the PR title and push a new commit or re-open the PR.
---
## Still Not Working?
Provide the following information when asking for help from `devops` team:
- Runner name and status (`kodo-review`)
- Workflow run URL
- Event that was expected to trigger the review
- Observed and expected behavior

45
docs/develoepr-guide/how-to-integrate.md Normal file
View File

@@ -0,0 +1,45 @@
# CI/CD integration for Gitea VCS
## Introduction
Manually launching and configuring the tool is quite a challenging task and requires a deep understanding of the AI service being used and the built-in operating rules. Therefore, to simplify the task, we have created pre-prepared actions for launching and updating the tool.
## 1. User for review
For the tool to work, you need to add a user who will perform the review. Add to `CODEOWNERS` file for repository if you want it to be assigned automatically, or add it manually if necessary.
Use this Gitea user by default: `@kodobot`.
## 2. Prepared step script for Gitea
Use the following script to integrate the tool into your Gitea actions. All necessary improvements and integrations must be performed independently by each team. Add your `.gitea/workflows/kodo-reviewer.yaml` file with the following content
``` yml
name: AI Code Reviewer Assistant for Gitea
on:
issue_comment:
types: [created]
pull_request_review_comment:
types: [created]
pull_request:
types: [opened, synchronize, reopened]
jobs:
claude-assistant:
runs-on: kodo-review
steps:
- name: Run AI Code Reviewer
uses: https://code.wynenterprise.io/kodo/reviewer@main
with:
gitea_token: ${{ secrets.CC_GITEATOKEN }}
anthropic_api_key: ${{ secrets.CC_API_KEY }}
```
This script will run automatically when a Pull Request is created or updated. If necessary, you can start it manually via the Gitea interface and add additional conditions required for start.
## 2.1. Environment variables for script
When configuring the tool, always strictly adhere to the following rules for certain environment variables:
1. The `secrets.CC_GITEATOKEN` environment variable must contain a token for the user @kodobot. **Request this token from the devops team.**
2. The `secrets.CC_API_KEY` environment variable must contain a token for access ti AI model. **Request this token from the devops team.**

37
docs/devops-guide/reviewer-token.md Normal file
View File

@@ -0,0 +1,37 @@
# Gitea Token Setup for AI Code Reviewer
## Required Token Permissions
| Permission | Level | Reason |
|---|---|---|
| **repository** | Read and Write | Read PR details, branches, diff; post review comments |
| **issue** | Read and Write | Create and delete progress comments on PRs (Gitea treats PR comments as issues internally) |
| **user** | Read | Fetch current bot user info to verify reviewer assignment |
All other permissions (`activitypub`, `misc`, `notification`, `organization`, `package`) should be set to **No Access**.
## How to Generate the Token
1. Log in to Gitea as the **bot account** that will be assigned as a reviewer
2. Go to **Settings** → **Applications** (top right avatar → Settings → Applications)
3. Under **Manage Access Tokens** click **Generate Token**
4. Fill in:
- **Token Name**: `ai-code-reviewer` (or any descriptive name)
- **Expiration**: set according to your security policy
5. Set permissions as described in the table above
6. Click **Generate Token**
7. **Copy the token immediately** — it will not be shown again
## Adding the Token to Your Repository
1. Go to your repository → **Settings** → **Secrets**
2. Click **Add Secret**
3. Set:
- **Name**: `CC_GITEATOKEN`
- **Value**: paste the token generated above
4. Click **Save**
## Important Notes
- The token must belong to the account that is **assigned as a reviewer** on pull requests — this is how the reviewer verification check works
- Treat the token as a password — never commit it to the repository

40
docs/user-guide/how-it-works.md Normal file
View File

@@ -0,0 +1,40 @@
# Gitea VCS Usage
## Introduction
When working with Gitea, you can use several methods to interact with the tool.
## 1. Launch of code review
To start a code review, you must first prepare the following:
1. Push the branch with changes to the remote repository
2. Create a Pull Request in Gitea VCS, adding the `@kodobot` reviewer user to the Pull Request
# 1.1. Automatic Start
After completing the preparatory stage of creating a Pull Request with the AI reviewer added, the code review **will be launched automatically.**
# 1.2. Manual Start
If for some reason you need to start the review yourself, use the `@kodobot` tag when writing a comment in the pull request.
# 2. Code review prevention
To prevent the review from starting, we can use the following methods
## 2.1. Tag [no ai] in the pull request title
When a pull request is created with the tag `[no ai]` in the pull request title, and when new changes are pushed to the pull request, the reviewer will not be triggered for that pull request.
This can be useful if you use `CODEOWNERS` file in your repository.
## 2.2. Do not add AI use to PR
You can choose not to add the `@kodobot` AI Reviewer user at all, and then the kodo review tool will never run for this Pull Request.
⚠️ **Important:** you **do not need** to write the `[no ai]` tag if no AI user has been added to the Pull Request for review.
## 3. Questions for AI
You can use the `@kodobot` tag in a Pull Request comment to ask the AI anything. After adding the `@kodobot` tag to your message you will receive a response from AI user.

43
docs/user-guide/limitations-and-best-practices.md Normal file
View File

@@ -0,0 +1,43 @@
# Limitations & Best Practices
## Limitations
### Context & Understanding
- **No business logic awareness** — AI only sees code, not product requirements
- **Limited context window** — the model has its own context window, which can hold a limited amount of information.
- **No decision history** — does not store the history of previous executions, only reads existing information in Pull Request.
- **Hallucinations** — may confidently suggest incorrect solutions or non-existent APIs
- **Large PR degradation** — review quality drops significantly for PRs with 1000+ lines changed
### Process Constraints
- **Does not replace humans** — final decision always belongs to the author and human reviewer
- **Slower on large PRs** — response time grows with the size of changes
- **No memory between PRs** — each review starts from scratch with no prior context
- **Trigger dependency** — only runs on configured events (`[no ai]` in title disables it)
## Best Practices
### Writing PRs for Better AI Review
- **Keep PRs small and focused** — one logical change per PR, ideally under 400 lines
- **Write a clear PR description** — explain *what* and *why*, not just *what changed*
- **Add `[no ai]` to title** when the PR is trivial (version bumps, typo fixes, formatting)
- **Split refactoring from feature changes** — mixed PRs confuse both AI and humans
### Working with AI Comments
- **Treat AI comments as suggestions, not mandates** — use your judgment
- **Verify all suggested code** before applying — AI can introduce bugs
- **Use `@kodobot` in comments** to ask follow-up questions about specific lines
- **Don't blindly resolve AI comments** — acknowledge or explain why you disagree
- **Re-trigger review after major changes** by pushing a new commit
### Security
- **Never put secrets in PR descriptions or comments** — AI logs may capture them
- **Store `anthropic_api_key` and `gitea_token` in repository secrets**, not in workflow files
- **Audit AI comments on security-sensitive PRs** (auth, crypto, infra) with extra care
### Team Workflow
- **Establish a policy** on when to override or ignore AI suggestions

37
docs/user-guide/what-is-kodo-reviewer.md Normal file
View File

@@ -0,0 +1,37 @@
# Kodo AI Reviewer
## 🤖 What is it?
Kodo AI Reviewer is an AI-powered automated code review tool. It integrates into your CI/CD pipeline, analyzes pull request changes, and helps teams maintain high code quality — without the bottlenecks of manual review.
---
## 🚀 Why use it?
| | Feature | What it means for you |
|---|---|---|
| ⏱️ | **Saves time** | Automates the routine review process so engineers focus on what matters |
| 📋 | **Single source of truth** | Consistent, reproducible feedback — no human bias or mood swings |
| 📈 | **Better code quality** | Catches style issues, logic flaws, and potential bugs comprehensively |
| 🕐 | **Always available** | Reviews code 24/7 — no waiting for a teammate to free up |
| 🔧 | **Highly customizable** | Extend built-in rules or create entirely new checks for your needs |
| 💬 | **Interactive** | Ask follow-up questions and get instant responses to your comments |
---
## 🌍 Where does it work?
Kodo AI Reviewer works directly inside your **CI/CD pipeline** — it runs automatically on every pull request, no extra setup required beyond the initial configuration.
---
## ✨ How does it work?
### 🔁 CI/CD Flow
When a pull request is opened or updated, Kodo kicks in automatically:
1. 📥 **Reads the environment** — loads your action configuration and prepares the review context
2. 🔍 **Analyzes your changes** — scans the diff for issues, improvements, and code quality signals
3. 💬 **Leaves comments** — posts inline feedback and a summary conclusion on the PR
4. 🗣️ *(Optional)* **Responds to you** — mention the predefined tag in any comment and Kodo will reply directly to your question or request