Updated README.md
This commit is contained in:
@@ -4,12 +4,5 @@ An AI-powered automated code review tool that integrates into your CI/CD pipelin
|
||||
|
||||
## Documentation
|
||||
|
||||
- [What is Kodo Reviewer?](docs/user-guide/what-is-kodo-reviewer.md)
|
||||
- [How it works](docs/user-guide/how-it-works.md)
|
||||
- [Limitations & best practices](docs/user-guide/limitations-and-best-practices.md)
|
||||
- [CI/CD integration guide](docs/develoepr-guide/how-to-integrate.md)
|
||||
- [Extending review rules](docs/develoepr-guide/extension-of-rules.md)
|
||||
- [Review output format](docs/develoepr-guide/ai-reviewer-output-format.md)
|
||||
- [Troubleshooting](docs/develoepr-guide/faq-troubleshooting.md)
|
||||
- [Token setup](docs/devops-guide/reviewer-token.md)
|
||||
- [Documentation](https://code.wynenterprise.io/kodo/reviewer/wiki)
|
||||
- [Action reference](action.yml)
|
||||
|
||||
@@ -1,101 +0,0 @@
|
||||
# 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
|
||||
```
|
||||
@@ -1,41 +0,0 @@
|
||||
# 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.
|
||||
|
||||
@@ -1,46 +0,0 @@
|
||||
# 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
|
||||
@@ -1,45 +0,0 @@
|
||||
# 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.**
|
||||
|
||||
@@ -1,37 +0,0 @@
|
||||
# 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
|
||||
@@ -1,40 +0,0 @@
|
||||
# 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.
|
||||
|
||||
@@ -1,43 +0,0 @@
|
||||
# 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
|
||||
@@ -1,37 +0,0 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user