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

Added the docs for Bitubcket VCS

Alexey Efimchik
2026-04-02 10:48:12 +07:00
parent 497b587b3d
commit a0c7307139
17 changed files with 1427 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

35
Home.md

@@ -23,6 +23,8 @@ Kodo AI Reviewer is an AI-powered automated code review tool. It integrates into
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.
Kodo supports multiple integrations: **Gitea**, **Bitbucket**, and a **local CLI tool** for running reviews on your machine.
---
## ✨ How does it work?
@@ -38,7 +40,7 @@ When a pull request is opened or updated, Kodo kicks in automatically:
---
## 📚 Documentation
## 📚 Gitea Documentation
### 👩‍💻 Developer
- [Code Review with Kodo](how-to-use) — how to trigger, skip, and interact with the reviewer
@@ -49,10 +51,39 @@ When a pull request is opened or updated, Kodo kicks in automatically:
- [CI/CD Integration](how-to-integrate) — how to add Kodo to your repository workflow
- [Extension of Existing Review Rules](extension-of-rules) — how to extend the built-in rules with project-specific instructions
- [Overriding Review Rules](overriding-rules) — How to completely override all instructions and create your own review agent
- [🛠️ Placeholder System](placeholder-system) — dynamic variables available in custom prompts
- [📝 Template: Technical Writing & Documentation](review-template-tech-writer) — grammar, clarity, structure, and content quality for docs and articles
- [🔒 Template: Security Review](review-template-security) — vulnerabilities, unsafe patterns, OWASP Top 10, secrets exposure
- [⚡ Template: Performance Review](review-template-performance) — bottlenecks, N+1 queries, memory leaks, algorithmic complexity
- [Troubleshooting](faq-troubleshooting) — what to check when Kodo doesn't run
- [Configuration and Parameters](configuration-parameters) — full reference of all action parameters
### ⚙️ DevOps
- [Gitea Token Setup](reviewer-token) — how to generate the bot token and configure repository secrets
- [Gitea Token Setup](reviewer-token) — how to generate the bot token and configure repository secrets
---
## 📚 Bitbucket Documentation
### 👩‍💻 Developer
- [Code Review with Kodo](bb-how-to-use) — how to trigger, skip, and interact with the reviewer
- [Review Output Format](ai-reviewer-output-format) — how to read summary comments, inline comments, and PR status
- [Limitations & Best Practices](bb-limitations-and-best-practices) — what Kodo can't do and how to get the most out of it
### 🧑‍🔧 Tech Lead
- [CI/CD Integration](bb-how-to-integrate) — how to add Kodo to your Bitbucket pipeline
- [Extension of Existing Review Rules](bb-extension-of-rules) — how to extend the built-in rules with project-specific instructions
- [Overriding Review Rules](bb-overriding-rules) — how to completely override all instructions and create your own review agent
- [🛠️ Placeholder System](bb-placeholder-system) — dynamic variables available in custom prompts
- [📝 Template: Technical Writing & Documentation](bb-review-template-tech-writer) — grammar, clarity, structure, and content quality for docs and articles
- [🔒 Template: Security Review](bb-review-template-security) — vulnerabilities, unsafe patterns, OWASP Top 10, secrets exposure
- [⚡ Template: Performance Review](bb-review-template-performance) — bottlenecks, N+1 queries, memory leaks, algorithmic complexity
- [Troubleshooting](bb-faq-troubleshooting) — what to check when Kodo doesn't run
- [Configuration and Parameters](bb-configuration-parameters) — full reference of all CI/CD environment variables
---
## 📚 Local Kodo Reviewer Documentation
- [🔀 Local Kodo Tool](local-kodo-tool) — how to install and run the reviewer locally
- [🔧 Overriding Local Settings](local-overriding-settings) — how to customize the local review prompt

42
_Sidebar.md

@@ -1,20 +1,50 @@
## 🤖 Kodo AI Reviewer
## 🤖 Kodo AI Reviewer
- [What is Kodo?](Kodo-AI-Reviewer)
- [What is Kodo?](Home)
### 👩‍💻 Developer
---
### 📚 Gitea
#### 👩‍💻 Developer
- [Code Review with Kodo](how-to-use)
- [Review Output Format](ai-reviewer-output-format)
- [Limitations & Best Practices](limitations-and-best-practices)
### 🧑‍🔧 Tech Lead
#### 🧑‍🔧 Tech Lead
- [CI/CD Integration](how-to-integrate)
- [Extension of Existing Review Rules](extension-of-rules)
- [Overriding Review Rules](overriding-rules)
- [Placeholder System](placeholder-system)
- [Template: Tech Writing](review-template-tech-writer)
- [Template: Security](review-template-security)
- [Template: Performance](review-template-performance)
- [Troubleshooting](faq-troubleshooting)
- [Configuration and Parameters](configuration-parameters)
### ⚙️ DevOps
- [Gitea Token Setup](reviewer-token)
---
### 📚 Bitbucket
#### 👩‍💻 Developer
- [Code Review with Kodo](bb-how-to-use)
- [Review Output Format](ai-reviewer-output-format)
- [Limitations & Best Practices](bb-limitations-and-best-practices)
#### 🧑‍🔧 Tech Lead
- [CI/CD Integration](bb-how-to-integrate)
- [Extension of Existing Review Rules](bb-extension-of-rules)
- [Overriding Review Rules](bb-overriding-rules)
- [Placeholder System](bb-placeholder-system)
- [Template: Tech Writing](bb-review-template-tech-writer)
- [Template: Security](bb-review-template-security)
- [Template: Performance](bb-review-template-performance)
- [Troubleshooting](bb-faq-troubleshooting)
- [Configuration and Parameters](bb-configuration-parameters)
---
### 📚 Local Kodo
- [Local Kodo Tool](local-kodo-tool)
- [Overriding Local Settings](local-overriding-settings)

47
bb-configuration-parameters.md Normal file

@@ -0,0 +1,47 @@
# 📋 Configuration and Parameters
## 📌 Introduction
This section contains complete reference information on all tool configuration parameters. Below is a list of available parameters for configuring the tool using CI/CD environment variables.
## 1. Description of environment variables
To configure the tool, you can use environment variables, which will be automatically recognized and used at startup.
1. `CC_BASE_URL` → Server address for the AI model. You usually need to ask the administrator what global environment variable they have set for your team and use that as the value for this variable. Each team has its own environment variable.
2. `CC_API_KEY` → API key for using the AI model. You usually need to ask the administrator what global environment variable they have set for your team and use that as the value for this variable. Each team has its own environment variable.
3. `CC_MODEL` → AI Model name. You usually need to ask the administrator what global environment variable they have set for your team and use that as the value for this variable. Each team has its own environment variable.
4. `VCS_ACCESS_TOKEN` → The reviewer's token with read and write permissions for PullRequests and repositories, as well as read permissions for user information. This is usually a common user for all teams. Ask the administrator about this value. As a rule, this is another global environment variable.
5. `WORKSPACE` → Workspace name. Usually located in the `$BITBUCKET_WORKSPACE` environment variable.
6. `REPO_SLUG` → Repository name. Usually located in the `$BITBUCKET_REPO_SLUG` environment variable.
7. `SOURCE_BRANCH` → Source branch name. Usually located in the `$BITBUCKET_BRANCH` environment variable.
8. `PR_ID` → Pull request ID. Usually located in the `$BITBUCKET_PR_ID` environment variable.
9. `SOURCE_COMMIT` → Commit hash of the source branch. Usually located in the `$BITBUCKET_COMMIT` environment variable.
10. `PR_DESTINATION_BRANCH` → Destination branch name. Usually located in the `$BITBUCKET_PR_DESTINATION_BRANCH` environment variable.
11. `PR_DESTINATION_COMMIT` → Commit hash of the destination branch. Usually located in the `$BITBUCKET_PR_DESTINATION_COMMIT` environment variable.
12. `ATLASSIAN_USER_EMAIL` → Reviewer's email address. This is usually a common user for all teams. Ask the administrator about this value. As a rule, this is another global environment variable.
13. `TEAM_NAME` → Reserved team name. It is important to set a value from a clearly defined list.
14. `LOG_LEVEL` → Logging level. Not usually used. Only if some kind of monitoring is required.
15. `OPTIONS_TYPE` → Value for determining the location of settings. Usually used to specify the location of settings for overriding the built-in review prompt.
16. `CC_PROMPT` → New prompt value. It is necessary to override the value of the prompt via `arguments`.
17. `CC_ALLOWED_TOOL` → List of permitted tools for AI. It is necessary to override the value of the allowed tools via arguments.
18. `CC_DISALLOWED_TOOL` → List of forbidden tools for AI. It is necessary to override the value of the forbidden tools via arguments.
19. `ENABLE_REVIEWER_VERIFICATION` → Value `true` or `false`. If not specified, the value `true` is used. Allows you to disable validation of Pull Request and reviewer presence. Useful when using an overridden value of the `OPTIONS_TYPE` variable.

91
bb-extension-of-rules.md Normal file

@@ -0,0 +1,91 @@
# 📐 Review Prompt Extension
The Kodo tool supports the ability to extend the built-in prompt for review.
## 📁 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.
The `.review` folder must be placed in the **root of your repository**.
```
my-project/
├── .review/ ← Create this folder
│ └── CONSTITUTION.md ← Your custom rules
├── src/
└── ...
```
## ✏️ 1.1. Examples of the `CONSTITUTION.md` file
**Example 1: Tell the reviewer what your linter already handles**
Use this to stop the AI from commenting on formatting, import order, and other things already enforced by your tooling.
```markdown
## Automated Tooling (Never Comment On These)
These are enforced automatically on every commit — mentioning them is noise:
- Formatting, indentation, trailing whitespace → Prettier
- Unused imports, import order → ESLint (import plugin)
- Semicolons, quote style → Prettier
- `console.log` removal → ESLint (no-console rule)
- Unused variables → TypeScript + ESLint
**If you would have flagged one of the above, stay silent.**
Only review what static analysis cannot catch: logic, intent, design decisions.
```
**Example 2: Give the reviewer context about your project**
Use this to prevent irrelevant suggestions and to make the reviewer aware of your critical invariants.
```markdown
## Project Context
App: B2B SaaS dashboard. Multi-tenant. Each request is scoped to a `tenantId`.
### Patterns already in place — do not suggest alternatives
- Data fetching → React Query. Do not suggest `useEffect` + `fetch`, SWR, or Axios.
- Forms → React Hook Form + Zod. Do not suggest Formik or manual validation.
- Global errors → caught in `ErrorBoundary` at root. Local boundaries are intentional only when present.
- Auth → handled in middleware. Do not flag missing auth checks inside route handlers.
- `/lib/api.ts` is our fetch wrapper — raw `fetch()` outside this file is always a bug.
### What to always flag
- Any query or filter that does not include `tenantId` — this is a data leak.
- Any hardcoded string that looks like a user-facing label (should use i18n keys).
- Direct state mutation (we use Immer, but only inside `produce()` blocks).
```
**Example 3: Control how many comments the reviewer leaves**
Use this to reduce noise and make sure real issues are always surfaced first.
```markdown
## Comment Rules
### Severity labels — use on every comment
🔴 BLOCKER — wrong behavior, data leak, broken edge case. List these first.
🟡 WARNING — will cause problems soon, but not an immediate break.
🔵 SUGGEST — optional, one sentence, only if genuinely useful.
### Noise reduction rules
- If a PR is under 50 lines: max 5 comments. Cut suggestions first.
- Do NOT comment on correct code to show you read it.
- Do NOT suggest extracting a function unless the current one exceeds 40 lines.
- Do NOT flag missing comments/JSDoc unless the function has non-obvious behavior.
- One comment per issue — do not repeat the same point in different locations.
### Start every review with one of these
- "🔴 X blockers found — must fix before merge." (then list them)
- "✅ No blockers. X warnings and Y suggestions below."
```
## 💡 1.2. Recommendations for the `CONSTITUTION.md` 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.

31
bb-faq-troubleshooting.md Normal file

@@ -0,0 +1,31 @@
# 🔧 Troubleshooting: Reviewer Did Not Run
## ✅ Quick Checklist
Before diving deeper, verify the basics:
- 📄 The workflow file exists at `./bitbucket-pipelines.yml`
- 🔑 The secrets are set in the repository settings by the `devops` team
- 🖥 The runner `kodo-review` is online and available
- 🏷 The commit message does **not** contain `[no ai]`
---
## 🔍 Common Causes & Fixes
**1. Commit contains `[no ai]`**
The agent checks for `[no ai]` in the commit text and skips execution if found.
**Fix:** Remove `[no ai]` from the commit message or push a new commit to the PR.
---
## 📨 Still Not Working?
Provide the following information when asking for help from the `devops` team:
- Runner name and status (`kodo-review`)
- Workflow run URL
- Event that was expected to trigger the review
- Observed and expected behavior

127
bb-how-to-integrate.md Normal file

@@ -0,0 +1,127 @@
# 🔌 CI/CD Integration for Bitbucket 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 user as the default reviewer for repository** if you want it to be assigned automatically, or add it manually if necessary.
Use this Bitbucket user by default: `@kodobot`.
## 📄 2. Prepared step script for Bitbucket
**Use the following script to integrate the tool into your Bitbucket pipelines.** All necessary improvements and integrations must be performed independently by each team. Consider using [Parallel steps](https://support.atlassian.com/bitbucket-cloud/docs/parallel-steps-in-pipelines/) in pipelines. Update your `bitbucket-pipelines.yml` file by adding the following:
**AR.NET Team**
```yaml
definitions:
steps:
- step: &ai-review-step
clone:
depth: full
name: AI Code Review
max-time: 40
image: code.wynenterprise.io/docker/bitbucket-ai-review:ar
runs-on: [kodo]
script:
- |
COMMIT_MSG=$(git log --format=%B -n 1 "$BITBUCKET_COMMIT")
if [[ "$COMMIT_MSG" == *"[no ai]"* ]]; then
echo "Skip pipeline: [no ai] found in commit message."
exit 0
fi
export VCS_ACCESS_TOKEN=$CC_KODOTOKEN
export ATLASSIAN_USER_EMAIL=$CC_KODOMAIL
export TEAM_NAME=$CC_TEAM
/pipe.sh
pipelines:
pull-requests:
'**':
- step: *ai-review-step
custom:
ai-review:
- step: *ai-review-step
```
**ARJS Team**
```yaml
definitions:
steps:
- step: &ai-review-step
clone:
depth: full
name: AI Code Review
max-time: 40
image: code.wynenterprise.io/docker/bitbucket-ai-review:arjs
runs-on: [kodo]
script:
- |
COMMIT_MSG=$(git log --format=%B -n 1 "$BITBUCKET_COMMIT")
if [[ "$COMMIT_MSG" == *"[no ai]"* ]]; then
echo "Skip pipeline: [no ai] found in commit message."
exit 0
fi
export VCS_ACCESS_TOKEN=$CC_KODOTOKEN
export ATLASSIAN_USER_EMAIL=$CC_KODOMAIL
export TEAM_NAME=$CC_TEAM
/pipe.sh
pipelines:
pull-requests:
'**':
- step: *ai-review-step
custom:
ai-review:
- step: *ai-review-step
```
**C1 Team**
```yaml
definitions:
steps:
- step: &ai-review-step
clone:
depth: full
name: AI Code Review
max-time: 40
image: code.wynenterprise.io/docker/bitbucket-ai-review:c1
runs-on: [kodo]
script:
- |
COMMIT_MSG=$(git log --format=%B -n 1 "$BITBUCKET_COMMIT")
if [[ "$COMMIT_MSG" == *"[no ai]"* ]]; then
echo "Skip pipeline: [no ai] found in commit message."
exit 0
fi
export VCS_ACCESS_TOKEN=$CC_KODOTOKEN
export ATLASSIAN_USER_EMAIL=$CC_KODOMAIL
export TEAM_NAME=$CC_TEAM
/pipe.sh
pipelines:
pull-requests:
'**':
- step: *ai-review-step
custom:
ai-review:
- step: *ai-review-step
```
This script will run automatically when a Pull Request is created or updated. If necessary, you can start it manually via the Bitbucket interface and add additional conditions required for start.
> ⚠️ **Important!** All pre-built scripts include a custom `ai-review` step. Do not change this name.

38
bb-how-to-use.md Normal file

@@ -0,0 +1,38 @@
# 👩‍💻 Code Review with Kodo
Kodo is an AI reviewer that automatically checks your code in Pull Requests and answers questions about the code.
## 🚀 Getting Started
To get an AI review on your Pull Request:
1. Push your branch to the remote repository
2. Create a Pull Request
3. Add `@kodobot` as a reviewer
That's it — Kodo will automatically review your code once added.
## 🔁 Starting a Review Manually
If you need to re-run the review or trigger it at a specific moment, just run the review pipeline manually using the Bitbucket UI.
## ⏭️ Skipping the Review
**Don't want Kodo to review a specific PR?** Simply don't add `@kodobot` as a reviewer.
**Want to disable the review even if `@kodobot` is added?** Add `[no ai]` to the commit text:
```
AR001: Fixed typo in README [no ai]
```
Kodo will not trigger on this commit.
## 💬 Asking Kodo a Question
You can ask Kodo anything about the code directly in a PR comment:
```
@kodobot what does this function do?
@kodobot is there a risk of a race condition here?
```
Kodo will respond in the comments **after manually running** the pipeline review script.

40
bb-limitations-and-best-practices.md Normal file

@@ -0,0 +1,40 @@
# ⚠️ 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
---
## ✅ 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*
- **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
- **Audit AI comments on security-sensitive PRs** (auth, crypto, infra) with extra care

165
bb-overriding-rules.md Normal file

@@ -0,0 +1,165 @@
# ⚙️ Overriding Review Rules
## 📌 Introduction
This section describes the basic principles of redefining the built-in prompt of the tool. This can be used to create your own rules during review.
> ⚠️ **Be careful** — when you override the rules, you override the **entire prompt**, including all review logic, output format, and tool permissions.
> ⚠️ **Important!** When you override settings, you must override **all** settings at once: the prompt, allowed tools, and disallowed tools. You do this by specifying the `OPTIONS_TYPE` variable in the Bitbucket pipeline config.
---
## 🔀 Override Methods
### 📁 Method 1: Overriding via a folder
Set the `OPTIONS_TYPE` parameter to `"folder"` and create a `.review/` folder in your repository with these 3 files:
```
my-project/
├── .review/
│ ├── PROMPT.md
│ ├── ALLOWED_TOOLS.md
│ └── DISALLOWED_TOOLS.md
├── src/
└── ...
```
**Bitbucket example:**
```yaml
definitions:
steps:
- step: &ai-review-step
clone:
depth: full
name: AI Code Review
max-time: 40
image: code.wynenterprise.io/docker/bitbucket-ai-review:{your team value}
runs-on: [kodo]
script:
- |
COMMIT_MSG=$(git log --format=%B -n 1 "$BITBUCKET_COMMIT")
if [[ "$COMMIT_MSG" == *"[no ai]"* ]]; then
echo "Skip pipeline: [no ai] found in commit message."
exit 0
fi
export VCS_ACCESS_TOKEN=$CC_KODOTOKEN
export ATLASSIAN_USER_EMAIL=$CC_KODOMAIL
export TEAM_NAME=$CC_TEAM
export OPTIONS_TYPE="folder"
/pipe.sh
pipelines:
pull-requests:
'**':
- step: *ai-review-step
custom:
ai-review:
- step: *ai-review-step
```
#### 1.1. Example content for `PROMPT.md`, `ALLOWED_TOOLS.md` and `DISALLOWED_TOOLS.md` files
Take a look at these examples of custom settings for a specific domain:
- [📝 Template: Technical Writing & Documentation](bb-review-template-tech-writer) — grammar, clarity, structure, and content quality for docs and articles
- [🔒 Template: Security Review](bb-review-template-security) — vulnerabilities, unsafe patterns, OWASP Top 10, secrets exposure
- [⚡ Template: Performance Review](bb-review-template-performance) — bottlenecks, N+1 queries, memory leaks, algorithmic complexity
Each template page contains a ready-to-use prompt, allowed tools list, and disallowed tools list, along with usage examples for both override methods.
---
### 📋 Method 2: Overriding via script arguments
Set the `OPTIONS_TYPE` parameter to `"arguments"` and pass the following three parameters directly in the pipeline config:
| Parameter | Description | Required |
|---|---|---|
| `CC_PROMPT` | New prompt for review | Yes |
| `CC_ALLOWED_TOOL` | List of allowed tools for the AI agent | Yes |
| `CC_DISALLOWED_TOOL` | List of disallowed tools for the AI agent | Yes |
**Bitbucket action example:**
```yaml
definitions:
steps:
- step: &ai-review-step
clone:
depth: full
name: AI Code Review
max-time: 40
image: code.wynenterprise.io/docker/bitbucket-ai-review:{your team value}
runs-on: [kodo]
script:
- |
COMMIT_MSG=$(git log --format=%B -n 1 "$BITBUCKET_COMMIT")
if [[ "$COMMIT_MSG" == *"[no ai]"* ]]; then
echo "Skip pipeline: [no ai] found in commit message."
exit 0
fi
export VCS_ACCESS_TOKEN=$CC_KODOTOKEN
export ATLASSIAN_USER_EMAIL=$CC_KODOMAIL
export TEAM_NAME=$CC_TEAM
export CC_PROMPT="New review rules for AI agent"
export CC_ALLOWED_TOOL="List of allowed tools for AI agent"
export CC_DISALLOWED_TOOL="List of disallowed tools for AI agent"
export OPTIONS_TYPE="arguments"
/pipe.sh
pipelines:
pull-requests:
'**':
- step: *ai-review-step
custom:
ai-review:
- step: *ai-review-step
```
Replace the values of `CC_PROMPT`, `CC_ALLOWED_TOOL` and `CC_DISALLOWED_TOOL` with your actual content.
#### 2.1. Example content for `CC_PROMPT`, `CC_ALLOWED_TOOL` and `CC_DISALLOWED_TOOL` variables
- [📝 Template: Technical Writing & Documentation](bb-review-template-tech-writer) — grammar, clarity, structure, and content quality for docs and articles
- [🔒 Template: Security Review](bb-review-template-security) — vulnerabilities, unsafe patterns, OWASP Top 10, secrets exposure
- [⚡ Template: Performance Review](bb-review-template-performance) — bottlenecks, N+1 queries, memory leaks, algorithmic complexity
---
## ⚠️ Important Limitations
**✅ Value for the `CC_ALLOWED_TOOL` variable and the `ALLOWED_TOOLS.md` file**
The list of allowed tools must always include the following:
```
mcp__serena, mcp__bitbucket__bb_get_pr, mcp__bitbucket__bb_get_file,
mcp__bitbucket__bb_ls_pr_comments, mcp__bitbucket__bb_add_pr_comment,
mcp__bitbucket__bb_update_pr_comment, mcp__bitbucket__bb_delete_pr_comment,
mcp__bitbucket__bb_approve_pr, mcp__bitbucket__bb_reject_pr,
mcp__bitbucket__bb_get_commit_history, mcp__bitbucket__bb_list_branches,
mcp__bitbucket__bb_search
```
You can expand it by adding your own, but we do not recommend removing anything from it.
**✅ Value for the `CC_DISALLOWED_TOOL` variable and the `DISALLOWED_TOOLS.md` file**
The list of disallowed tools must always include the following:
```
WebSearch, Bash(git diff:*), Bash(git push:*), Bash(rm:*), Bash(git diff:*)
```
You can expand it by adding your own, but we do not recommend removing anything from it.

96
bb-placeholder-system.md Normal file

@@ -0,0 +1,96 @@
# 🛠️ Placeholder System
## 📌 Introduction
This section describes the system for replacing placeholders in instrument setup files. This is useful when redefining prompts and other custom settings.
## 1. What are Placeholders
**Placeholders** are special markers in the format `%NAME%` that are automatically replaced with corresponding values during execution.
**Example:**
```
<!-- Before replacement -->
Repository: %REPOSITORY%, PR: #%PRID%, %SOURCE_BRANCH% → %TARGET_BRANCH%
<!-- After replacement -->
Repository: my-project, PR: 123, feature/new-login → main
```
This is used when creating new prompts and other customizations. See examples in the templates.
---
## 2. Available Placeholders
### 2.1. Common Placeholders (for all VCS)
| Placeholder | Description | Example Value |
|---|---|---|
| `%VCS%` | VCS system type | `Bitbucket` |
| `%SOURCE_BRANCH%` | Source branch (with changes) | `feature/add-auth` |
| `%TARGET_BRANCH%` | Target branch (merge destination) | `main` |
| `%REPOSITORY%` | Repository name | `backend-api` |
| `%PRID%` | Pull Request ID | `456` |
| `%COMMIT%` | Commit SHA in source branch | `abc123def456789` |
| `%TARGETBRANCHCOMMIT%` | Commit SHA in target branch | `xyz789abc123456` |
### 2.2. Bitbucket-Specific Placeholders
| Placeholder | Description | Example Value |
|---|---|---|
| `%WORKSPACE%` | Bitbucket workspace | `my-company` |
### 2.3. Where Placeholders Work
Placeholders are supported if you use `OPTIONS_TYPE` CI/CD env with the values `folder` or `arguments`. **This only works for CI/CD configuration and setting overrides.**
| File/Parameter | Support | Note |
|---|---|---|
| `.review/PROMPT.md` or `CC_PROMPT` | ✅ Yes | — |
| `.review/ALLOWED_TOOLS.md` or `CC_ALLOWED_TOOL` | ❌ No | Placeholders not supported |
| `.review/DISALLOWED_TOOLS.md` or `CC_DISALLOWED_TOOL` | ❌ No | Placeholders not supported |
| `.review/CONSTITUTION.md` | ❌ No | Placeholders not supported |
---
## 3. Usage Examples
Below is an example of using placeholders when overriding a prompt using **`.review/PROMPT.md`** file:
```markdown
# AI Code Reviewer for %REPOSITORY%
## Repository Info
- VCS: %VCS%
- Repository: %REPOSITORY%
- Workspace: %WORKSPACE%
## Pull Request Context
- PR: #%PRID%
- Branch: %SOURCE_BRANCH% → %TARGET_BRANCH%
- Commits: %COMMIT% → %TARGETBRANCHCOMMIT%
## Your Role
Review PR #%PRID% for %REPOSITORY%, comparing %SOURCE_BRANCH% against %TARGET_BRANCH%.
```
After replacement it will look like this:
```markdown
# AI Code Reviewer for backend-api
## Repository Info
- VCS: Bitbucket
- Repository: backend-api
- Workspace: acme-corp
## Pull Request Context
- PR: #123
- Branch: feature/add-auth → main
- Commits: abc123def → xyz789abc
## Your Role
Review PR #123 for backend-api, comparing feature/add-auth against main.
```

165
bb-review-template-performance.md Normal file

@@ -0,0 +1,165 @@
# ⚡ Template: Performance Review
This template is designed for performance-focused code review. The AI agent will prioritize identifying bottlenecks, inefficient algorithms, unnecessary resource usage, and scalability concerns.
Before creating and viewing review templates, read the information about the placeholder system and how it works: [🛠️ Placeholder System](bb-placeholder-system)
---
## 🤖 Prompt (`CC_PROMPT` / `PROMPT.md`)
```
# Context Description
Review code changes for performance regressions and optimization opportunities.
# AI Performance Reviewer — Bitbucket
# Bitbucket VCS Context
You must review the following Bitbucket Pull Request:
- Source Branch: %SOURCE_BRANCH%
- Source Branch Commit: %COMMIT%
- Target Branch: %TARGET_BRANCH%
- Target Branch Commit: %TARGETBRANCHCOMMIT%
- Workspace: %WORKSPACE%
- Repository Name: %REPOSITORY%
- Pull Request Id: %PRID%
## Role Definition
You are an **AI performance reviewer** with direct access to Bitbucket through MCP tools.
Your mission is to identify performance regressions, algorithmic inefficiencies, resource
waste, and scalability bottlenecks introduced by this Pull Request, and post structured
feedback as **inline comments attached to specific lines of code**.
Focus on changes that will matter at production scale. Do not flag micro-optimizations
that have no measurable impact. Every finding must state its impact in concrete terms.
**YOU MUST FINISH THE REVIEW BY:**
1. Posting all inline comments via `mcp__bitbucket__bb_add_pr_comment` attached to the
exact line numbers from the RIGHT COLUMN of `.review/diff.patch`
2. Posting a summary general comment via `mcp__bitbucket__bb_add_pr_comment`
3. Calling `mcp__bitbucket__bb_approve_pr` or `mcp__bitbucket__bb_reject_pr`
**A REVIEW WITHOUT INLINE COMMENTS ATTACHED TO CODE LINES IS INCOMPLETE.**
---
## STEP 2 — Performance Review
### 2.1 Review categories
**Algorithmic Complexity**
- Identify complexity regressions: O(n²) where O(n log n) or O(n) is achievable
- Nested loops over the same or related collections — look for quadratic patterns
- Repeated linear scans that could be replaced by a hash map or index
- Recursive functions without memoization or tail-call optimization where applicable
**Database & I/O**
- N+1 query patterns: queries inside loops or lazy-loaded relations iterated in a loop
- Missing indexes implied by new filter/order/join conditions added in queries
- Fetching full rows or all columns when only a subset is needed (`SELECT *`)
- Unbounded queries without pagination, limit, or cursor on potentially large tables
- Synchronous I/O on a thread that should remain non-blocking
**Memory**
- Unbounded collection growth: appending to a list inside a loop without a size cap
- Large objects or datasets loaded entirely into memory when streaming is possible
- Memory leaks: resources (file handles, connections, timers) opened but not closed
**Concurrency**
- Lock contention: coarse-grained locks protecting code that doesn't need full exclusion
- Sequential execution of independent I/O operations that could run in parallel
- Thread pool exhaustion: blocking calls on a limited thread pool (e.g. async/await misuse)
**Caching**
- Repeated computation of the same value within a request or across requests
- Missing cache invalidation on write paths that would serve stale data
**Network & Serialization**
- Chatty APIs: multiple round trips that could be batched into one
- Large payloads sent in full when partial/compressed responses are possible
### 2.2 Impact classification
| Impact | When to use |
|---|---|
| REGRESSION | Measurably slower or higher resource usage than the current target branch |
| HIGH | Significant degradation at scale (e.g. O(n²) on user-sized data, N+1 on a list page) |
| MEDIUM | Noticeable under load but unlikely to cause incidents |
| LOW | Minor inefficiency with negligible real-world impact |
Do NOT flag LOW impact issues unless they appear inside a documented hot path.
---
## STEP 3 — Post Inline Comments
**Format (MUST follow exactly):**
```
[⛔|⚠️|ℹ️] [Issue|Suggestion|Note] ([REGRESSION|HIGH|MEDIUM|LOW] Performance): [Description]
📊 Impact: [Concrete description of the effect at scale]
⚡ Suggested Fix:
```language
[optimized code]
```
```
**Icons:**
- ⛔ = REGRESSION or HIGH impact
- ⚠️ = MEDIUM impact
- ℹ️ = LOW impact (only inside documented hot paths)
---
## STEP 4 — Post Summary Comment
**Template (MUST follow exactly):**
```
[⛔|⚠️|✅] Performance assessment: [Regression|Degraded|Neutral|Improved]
📊 Impact summary:
- REGRESSION: [count] findings
- HIGH: [count] findings
- MEDIUM: [count] findings
- LOW: [count] findings
ℹ️ Conclusion: [Overall performance posture of the changes]
[✅|❌] Merge: [Yes/No — brief reason]
```
---
## STEP 5 — Approve or Reject (REQUIRED — MUST NOT BE SKIPPED)
- **APPROVED** — no REGRESSION or HIGH findings → call `mcp__bitbucket__bb_approve_pr`
- **REQUEST_CHANGES** — any REGRESSION or HIGH finding → call `mcp__bitbucket__bb_reject_pr`
```
---
## ✅ Allowed Tools (`CC_ALLOWED_TOOL` / `ALLOWED_TOOLS.md`)
```
Bash, Edit, MultiEdit, Glob, Grep, LS, Read, Write, mcp__serena,
mcp__bitbucket__bb_get_pr, mcp__bitbucket__bb_get_file,
mcp__bitbucket__bb_ls_pr_comments, mcp__bitbucket__bb_add_pr_comment,
mcp__bitbucket__bb_update_pr_comment, mcp__bitbucket__bb_delete_pr_comment,
mcp__bitbucket__bb_approve_pr, mcp__bitbucket__bb_reject_pr,
mcp__bitbucket__bb_get_commit_history, mcp__bitbucket__bb_list_branches,
mcp__bitbucket__bb_search
```
> 💡 The list above is the recommended baseline. You may extend it with additional tools specific to your setup.
---
## 🚫 Disallowed Tools (`CC_DISALLOWED_TOOL` / `DISALLOWED_TOOLS.md`)
```
WebSearch, Bash(git diff:*), Bash(git push:*), Bash(rm:*), Bash(git diff:*)
```
> 💡 The list above is the recommended baseline. You may extend it with additional restrictions as needed.

170
bb-review-template-security.md Normal file

@@ -0,0 +1,170 @@
# 🔒 Template: Security Review
This template is designed for security-focused code review. The AI agent will prioritize identifying vulnerabilities, unsafe patterns, and security risks in the submitted code changes.
Before creating and viewing review templates, read the information about the placeholder system and how it works: [🛠️ Placeholder System](bb-placeholder-system)
---
## 🤖 Prompt (`CC_PROMPT` / `PROMPT.md`)
```
# Context Description
Review code changes for security vulnerabilities in the specified branches.
# AI Security Reviewer — Bitbucket
# Bitbucket VCS Context
You must review the following Bitbucket Pull Request:
- Source Branch: %SOURCE_BRANCH%
- Source Branch Commit: %COMMIT%
- Target Branch: %TARGET_BRANCH%
- Target Branch Commit: %TARGETBRANCHCOMMIT%
- Workspace: %WORKSPACE%
- Repository Name: %REPOSITORY%
- Pull Request Id: %PRID%
## Role Definition
You are an **AI security reviewer** with direct access to Bitbucket through MCP tools.
Your mission is to identify security vulnerabilities, insecure patterns, and compliance
risks introduced by this Pull Request, and post structured feedback as **inline comments
attached to specific lines of code**.
Treat every finding with the assumption that it will be exploited. Your job is not to
theorize — it is to identify concrete, exploitable risks and provide actionable fixes.
**YOU MUST FINISH THE REVIEW BY:**
1. Posting all inline comments via `mcp__bitbucket__bb_add_pr_comment` attached to the
exact line numbers from the RIGHT COLUMN of `.review/diff.patch`
2. Posting a summary general comment via `mcp__bitbucket__bb_add_pr_comment`
3. Calling `mcp__bitbucket__bb_approve_pr` or `mcp__bitbucket__bb_reject_pr`
**A REVIEW WITHOUT INLINE COMMENTS ATTACHED TO CODE LINES IS INCOMPLETE.**
---
## STEP 2 — Security Review
### 2.1 Threat categories to check
**Injection**
- SQL injection: string concatenation in queries, unparameterized inputs
- Command injection: shell calls with user-supplied data, unsafe `exec`/`eval`/`system`
- LDAP, XPath, NoSQL, template injection patterns
- Log injection: unsanitized user input written directly to logs
**Authentication & Authorization**
- Hardcoded credentials, tokens, API keys, or passwords in any form
- Secrets committed to source (even in tests or comments)
- Missing or bypassable authentication on new endpoints or functions
- Broken access control: missing ownership checks, IDOR patterns
- Insecure session handling: long-lived tokens, missing expiry, insecure storage
**Cryptography**
- Use of deprecated algorithms (MD5, SHA-1, DES, RC4, ECB mode)
- Hardcoded or weak keys, IVs, or salts
- Missing certificate validation or `verify=False` patterns
**Data Exposure**
- Sensitive data (PII, credentials, health data) logged or returned in error messages
- Unencrypted storage or transmission of sensitive data
- Overly broad API responses exposing internal fields
**Input Validation & Output Encoding**
- Missing validation on user-supplied inputs (type, length, format, range)
- Missing output encoding in HTML, JS, SQL, XML contexts (XSS vectors)
- Path traversal: unsanitized file paths constructed from user input
**Dependency & Supply Chain**
- New dependencies added without pinned versions
- Dependencies with known CVEs
- Use of deprecated or abandoned packages
**Configuration & Secrets**
- Debug flags, verbose logging, or development modes enabled
- Permissive CORS, CSP, or security header configurations
- Sensitive configuration values stored in code rather than environment variables
### 2.2 Severity classification
| Severity | When to use |
|---|---|
| CRITICAL | Directly exploitable with no preconditions (e.g. SQLi, RCE, hardcoded secret) |
| HIGH | Exploitable with low effort or common preconditions (e.g. IDOR, XSS, weak crypto) |
| MEDIUM | Requires specific conditions or partial mitigations exist |
| LOW | Defense-in-depth, best practice, or theoretical risk |
---
## STEP 3 — Post Inline Comments
**Format (MUST follow exactly):**
```
[⛔|⚠️|ℹ️] [Issue|Suggestion|Note] ([CRITICAL|HIGH|MEDIUM|LOW] Security): [Description]
Attack vector: [Concrete scenario — how this could be exploited]
🔒 Suggested Fix:
```language
[secure code that resolves the vulnerability]
```
```
**Icons:**
- ⛔ = CRITICAL or HIGH severity
- ⚠️ = MEDIUM severity
- ℹ️ = LOW severity
---
## STEP 4 — Post Summary Comment
**Template (MUST follow exactly):**
```
[⛔|⚠️|✅] Security assessment: [High Risk|Medium Risk|Low Risk|Clear]
🔍 Threat summary:
- CRITICAL: [count] findings
- HIGH: [count] findings
- MEDIUM: [count] findings
- LOW: [count] findings
ℹ️ Conclusion: [Overall security posture of the changes]
[✅|❌] Merge: [Yes/No — brief reason]
```
---
## STEP 5 — Approve or Reject (REQUIRED — MUST NOT BE SKIPPED)
- **APPROVED** — no CRITICAL or HIGH findings → call `mcp__bitbucket__bb_approve_pr`
- **REQUEST_CHANGES** — any CRITICAL or HIGH finding → call `mcp__bitbucket__bb_reject_pr`
```
---
## ✅ Allowed Tools (`CC_ALLOWED_TOOL` / `ALLOWED_TOOLS.md`)
```
Bash, Edit, MultiEdit, Glob, Grep, LS, Read, Write, mcp__serena,
mcp__bitbucket__bb_get_pr, mcp__bitbucket__bb_get_file,
mcp__bitbucket__bb_ls_pr_comments, mcp__bitbucket__bb_add_pr_comment,
mcp__bitbucket__bb_update_pr_comment, mcp__bitbucket__bb_delete_pr_comment,
mcp__bitbucket__bb_approve_pr, mcp__bitbucket__bb_reject_pr,
mcp__bitbucket__bb_get_commit_history, mcp__bitbucket__bb_list_branches,
mcp__bitbucket__bb_search
```
> 💡 The list above is the recommended baseline. You may extend it with additional tools specific to your setup.
---
## 🚫 Disallowed Tools (`CC_DISALLOWED_TOOL` / `DISALLOWED_TOOLS.md`)
```
WebSearch, Bash(git diff:*), Bash(git push:*), Bash(rm:*), Bash(git diff:*)
```
> 💡 The list above is the recommended baseline. You may extend it with additional restrictions as needed.

193
bb-review-template-tech-writer.md Normal file

@@ -0,0 +1,193 @@
# 📝 Template: Technical Writing & Documentation
This template is designed for reviewing documentation, articles, changelogs, and other technical writing. The AI agent will focus on grammar, clarity, structure, and content quality rather than code.
Before creating and viewing review templates, read the information about the placeholder system and how it works: [🛠️ Placeholder System](bb-placeholder-system)
---
## 🤖 Prompt (`CC_PROMPT` / `PROMPT.md`)
```
# Context Description
Review documentation and technical writing changes for the specified branches.
# AI Documentation Reviewer — Bitbucket
# Bitbucket VCS Context
You must review the following Bitbucket Pull Request:
- Source Branch: %SOURCE_BRANCH%
- Source Branch Commit: %COMMIT%
- Target Branch: %TARGET_BRANCH%
- Target Branch Commit: %TARGETBRANCHCOMMIT%
- Workspace: %WORKSPACE%
- Repository Name: %REPOSITORY%
- Pull Request Id: %PRID%
## Role Definition
You are an **AI technical writing reviewer** with direct access to Bitbucket through MCP tools.
Your mission is to review documentation changes — including README files, API docs, inline
code comments, changelogs, wikis, and any prose in the repository — and post structured
feedback as **inline comments attached to specific lines**.
**YOU MUST FINISH THE REVIEW BY:**
1. Posting all inline comments via `mcp__bitbucket__bb_add_pr_comment` attached to the
exact line numbers from the RIGHT COLUMN of `.review/diff.patch`
2. Posting a summary general comment via `mcp__bitbucket__bb_add_pr_comment`
3. Calling `mcp__bitbucket__bb_approve_pr` or `mcp__bitbucket__bb_reject_pr`
**A REVIEW WITHOUT INLINE COMMENTS ATTACHED TO CODE LINES IS INCOMPLETE.**
---
## REQUIRED FIRST ACTION
Before starting any review step, you MUST:
1. **Read `.review/CONSTITUTION.md`** — if the file exists, read it fully. All rules defined
in it MUST be applied throughout the entire review.
2. **Read `.review/CLAUDE.md`** — if the file exists, read it fully before proceeding.
These files define project-specific rules that override general review guidelines.
Reading them after the review has started is not acceptable.
---
## REQUIRED FINAL ACTION
The final three actions MUST be executed in this exact order — no exceptions:
1. **Post all inline comments** (Step 3)
2. **Post the summary comment** (Step 4) — after ALL inline comments are posted
3. **Approve or reject the PR** (Step 5) — last, after the summary comment
Skipping or reordering any of these three actions means the review is considered **FAILED**.
---
## STEP 1 — Pre-Review Setup
### 1.1 Read CONSTITUTION
Check if `.review/CONSTITUTION.md` exists. If yes — read it fully and apply every rule
throughout the entire review.
### 1.2 Read CLAUDE.md
Check if `.review/CLAUDE.md` exists. If yes — read it.
### 1.3 Exclude local changes
Add all uncommitted local changes to `.git/info/exclude`. Do not mention these files
in review comments.
### 1.4 Load existing PR comments
Use `mcp__bitbucket__bb_ls_pr_comments` to retrieve ALL existing comments from the Pull Request.
---
## STEP 2 — Documentation Review
### 2.1 Review criteria
Evaluate every changed documentation file against the following dimensions:
**Clarity & Readability**
- Is the text clear and unambiguous? Would a target reader understand it without prior context?
- Are sentences concise? Flag sentences over 35 words as candidates for splitting.
- Is the vocabulary appropriate for the stated or implied audience (end user, developer, ops)?
**Accuracy & Completeness**
- Do code samples, commands, and API signatures match the actual code in the repository?
- Are parameters, return values, error codes, and edge cases documented?
- Are version numbers, deprecation notices, and compatibility notes up to date?
- Are there missing sections that readers would reasonably expect (e.g. Prerequisites, Examples, Troubleshooting)?
**Structure & Formatting**
- Is the document logically structured? Do headings follow a hierarchy (H1 → H2 → H3)?
- Are lists used consistently (all bullets or all numbered, not mixed arbitrarily)?
- Are code blocks used for all commands, file paths, and inline identifiers?
- Is the formatting consistent with surrounding documents in the repository?
**Grammar & Language**
- Flag spelling errors, grammatical mistakes, and awkward phrasing.
- Flag passive voice where active voice would be clearer.
- Flag undefined acronyms on first use.
**Consistency**
- Are terms used consistently throughout the document and with other docs in the repo?
- Does capitalization follow a single convention?
- Are cross-references and links valid and pointing to the right targets?
### 2.2 Diff rules (CRITICAL)
- ✅ Comment ONLY on NEW lines — right column of `.review/diff.patch`
- ✅ Use line numbers from the RIGHT COLUMN only
- ✅ Before posting any inline comment — check existing comments and SKIP if duplicate
- ❌ Do NOT comment on unchanged lines or lines from `%TARGET_BRANCH%`
- ❌ Do NOT post inline feedback as a general comment — every issue MUST be attached to its line number
---
## STEP 3 — Post Inline Comments
For each issue found, post an inline comment attached to the exact line using `mcp__bitbucket__bb_add_pr_comment`.
**Format (MUST follow exactly):**
```
[⛔|⚠️|ℹ️] [Suggestion|Issue|TODO|Typo|Note|Polish] ([Non Blocking|Blocking]): [Description]
✏️ Suggested Text:
[corrected or improved prose/markup that replaces the flagged content]
```
**Icons:**
- ⛔ = Factually incorrect, broken example, missing critical information
- ⚠️ = Unclear, incomplete, or inconsistent content
- ℹ️ = Style, grammar, or minor improvement
---
## STEP 4 — Post Summary Comment
After ALL inline comments are posted, add a general PR comment using `mcp__bitbucket__bb_add_pr_comment`.
**Template (MUST follow exactly):**
```
[⛔|⚠️|✅] Documentation quality assessment: [Poor|Acceptable|Excellent]
ℹ️ Conclusion: [Overall analysis — clarity, accuracy, completeness, consistency]
[✅|❌] Merge: [Yes/No — brief reason]
```
---
## STEP 5 — Approve or Reject (REQUIRED — MUST NOT BE SKIPPED)
- **APPROVED** — no blocking issues found → call `mcp__bitbucket__bb_approve_pr`
- **REQUEST_CHANGES** — one or more blocking issues found → call `mcp__bitbucket__bb_reject_pr`
```
---
## ✅ Allowed Tools (`CC_ALLOWED_TOOL` / `ALLOWED_TOOLS.md`)
```
Bash, Edit, MultiEdit, Glob, Grep, LS, Read, Write, mcp__serena,
mcp__bitbucket__bb_get_pr, mcp__bitbucket__bb_get_file,
mcp__bitbucket__bb_ls_pr_comments, mcp__bitbucket__bb_add_pr_comment,
mcp__bitbucket__bb_update_pr_comment, mcp__bitbucket__bb_delete_pr_comment,
mcp__bitbucket__bb_approve_pr, mcp__bitbucket__bb_reject_pr,
mcp__bitbucket__bb_get_commit_history, mcp__bitbucket__bb_list_branches,
mcp__bitbucket__bb_search
```
> 💡 The list above is the recommended baseline. You may extend it with additional tools specific to your setup.
---
## 🚫 Disallowed Tools (`CC_DISALLOWED_TOOL` / `DISALLOWED_TOOLS.md`)
```
WebSearch, Bash(git diff:*), Bash(git push:*), Bash(rm:*), Bash(git diff:*)
```
> 💡 The list above is the recommended baseline. You may extend it with additional restrictions as needed.

49
configuration-parameters.md Normal file

@@ -0,0 +1,49 @@
# 📋 Configuration and Parameters
## 📌 Introduction
This section contains complete reference information on all tool configuration parameters. The tool can be configured either via **action inputs** (in the `with:` block of your Gitea action) or via **environment variables** — each input has a corresponding environment variable with the same name in uppercase.
## 1. Description of parameters
1. `gitea_token` → The reviewer's token with read and write permissions for Pull Requests and repositories. This is usually a shared user for all teams. Ask the administrator about this value. As a rule, this is another global environment variable.
2. `anthropic_api_key` → API key for using the AI model. You usually need to ask the administrator what global environment variable they have set for your team and use that as the value for this parameter. Each team has its own environment variable.
3. `model` / `CC_MODEL` → Model name to use for the review. You usually need to ask the administrator what global environment variable they have set for your team and use that as the value for this parameter. Each team has its own environment variable.
4. `cc_bgmodel` / `CC_BGMODEL` → Background Claude model to use for lightweight tasks during review.
5. `cc_base_url` / `CC_BASE_URL` → Base URL for the Claude API endpoint. You usually need to ask the administrator what global environment variable they have set for your team and use that as the value for this parameter. Each team has its own environment variable.
6. `cc_metric_url` / `CC_METRIC_URL` → Base URL for the metrics API endpoint. Used for telemetry collection.
7. `server` / `SERVER` → Gitea server URL. Specifies the address of the Gitea instance the tool connects to.
8. `repo_owner` / `REPO_OWNER` → Repository owner name. Specifies who owns the repository being reviewed. Defaults to the owner from the action context.
9. `repo_slug` / `REPO_SLUG` → Repository slug/name. Defaults to the repository name from the action context.
10. `source_branch` / `SOURCE_BRANCH` → Source branch name (with changes). Defaults to `GITHUB_HEAD_REF`.
11. `source_commit` / `SOURCE_COMMIT` → Commit hash of the source branch.
12. `pr_id` / `PR_ID` → Pull Request ID.
13. `pr_destination_branch` / `PR_DESTINATION_BRANCH` → Destination (target) branch name — the branch into which the PR will be merged.
14. `pr_destination_commit` / `PR_DESTINATION_COMMIT` → Commit hash of the destination branch.
15. `team_name` / `TEAM_NAME` → Reserved team name for telemetry and metrics attribution. It is important to set a value from a clearly defined list.
16. `log_level` / `LOG_LEVEL` → Logging level. Not usually used. Only if some kind of monitoring is required.
17. `options_type` / `OPTIONS_TYPE` → Value for determining the location of settings. Usually used to specify the location of settings for overriding the built-in review prompt.
18. `cc_prompt` / `CC_PROMPT` → Custom prompt override for the AI review. Required when using `options_type: arguments`.
19. `cc_allowed_tool` / `CC_ALLOWED_TOOL` → List of permitted tools for the AI agent. Required when using `options_type: arguments`.
20. `cc_disallowed_tool` / `CC_DISALLOWED_TOOL` → List of forbidden tools for the AI agent. Required when using `options_type: arguments`.
21. `enable_reviewer_verification` / `ENABLE_REVIEWER_VERIFICATION` → Value `true` or `false`. If not specified, the value `true` is used. Allows you to disable validation of Pull Request and reviewer presence. Useful when using an overridden value of the `options_type` parameter.

40
local-kodo-tool.md Normal file

@@ -0,0 +1,40 @@
# 🔀 Local Kodo Tool
## 📌 Introduction
You can use the AI review tool locally. This will simplify the development and verification of changes.
## 🔍 Requirements
To use the Claude Code AI-powered code checking tool, you will need the following:
1. .NET 8+ installed
2. The latest version of Claude Code CLI installed
3. An active subscription for Claude Code CLI
4. Git tool installed and project with repository
## 1. Tool installation
Use the following command to install the tool in your environment:
```
dotnet tool install --global DT.AIReview.Tool
```
## 2. Review of changes
Go to the project where the repository and branch with your changes exist:
```
cd your-awesome-project
```
Then execute the command to launch the AI review tool:
```
ai-review --vcs="local"
```
## 3. Review results
As a result of the tool's work, in the folder where you executed the review command, you will see a file named **"review-result.md"** that contains detailed results with a review of the changes between the base and target branches.

7
local-overriding-settings.md Normal file

@@ -0,0 +1,7 @@
# 🔧 Overriding Local Settings
You can view and override the local prompt for review. **After performing your first local review**, a `.review` folder will be created with a file named `kodo-review-prompt.md` which will contain the review prompt.
**Open the existing file and modify it.** The modified version of the file will be used for future executions. You can also manually create a file named `.review/kodo-review-prompt.md` that will be used for reviewing.
> ⚠️ **Important!** ⚠️ The prompt is redefined at the location where the tool is called. This is **not** a global redefinition.

99
placeholder-system.md Normal file

@@ -0,0 +1,99 @@
# 🛠️ Placeholder System
## 📌 Introduction
This section describes the system for replacing placeholders in instrument setup files. This is useful when redefining prompts and other custom settings.
## 1. What are Placeholders
**Placeholders** are special markers in the format `%NAME%` that are automatically replaced with corresponding values during execution.
**Example:**
```
<!-- Before replacement -->
Repository: %REPOSITORY%, PR: #%PRID%, %SOURCE_BRANCH% → %TARGET_BRANCH%
<!-- After replacement -->
Repository: my-project, PR: 123, feature/new-login → main
```
This is used when creating new prompts and other customizations. See examples in the templates.
---
## 2. Available Placeholders
### 2.1. Common Placeholders (for all VCS)
| Placeholder | Description | Example Value |
|---|---|---|
| `%VCS%` | VCS system type | `Gitea` |
| `%SOURCE_BRANCH%` | Source branch (with changes) | `feature/add-auth` |
| `%TARGET_BRANCH%` | Target branch (merge destination) | `main` |
| `%REPOSITORY%` | Repository name | `backend-api` |
| `%PRID%` | Pull Request ID | `456` |
| `%COMMIT%` | Commit SHA in source branch | `abc123def456789` |
| `%TARGETBRANCHCOMMIT%` | Commit SHA in target branch | `xyz789abc123456` |
### 2.2. Gitea-Specific Placeholders
| Placeholder | Description | Example Value |
|---|---|---|
| `%OWNER%` | Repository owner | `my-team` |
| `%BASEURL%` | Gitea server address | `https://code.example.io` |
### 2.3. Where Placeholders Work
Placeholders are supported if you use `options_type` with the values `folder` or `arguments`. **This only works for CI/CD configuration and setting overrides.**
| File/Parameter | Support | Note |
|---|---|---|
| `.review/PROMPT.md` or `cc_prompt` | ✅ Yes | — |
| `.review/ALLOWED_TOOLS.md` or `cc_allowed_tool` | ❌ No | Placeholders not supported |
| `.review/DISALLOWED_TOOLS.md` or `cc_disallowed_tool` | ❌ No | Placeholders not supported |
| `.review/CONSTITUTION.md` | ❌ No | Placeholders not supported |
---
## 3. Usage Examples
Below is an example of using placeholders when overriding a prompt using **`.review/PROMPT.md`** file:
```markdown
# AI Code Reviewer for %REPOSITORY%
## Repository Info
- VCS: %VCS%
- Server: %BASEURL%
- Owner: %OWNER%
- Repository: %REPOSITORY%
## Pull Request Context
- PR: #%PRID%
- Branch: %SOURCE_BRANCH% → %TARGET_BRANCH%
- Commits: %COMMIT% → %TARGETBRANCHCOMMIT%
## Your Role
Review PR #%PRID% for %REPOSITORY%, comparing %SOURCE_BRANCH% against %TARGET_BRANCH%.
```
After replacement it will look like this:
```markdown
# AI Code Reviewer for backend-api
## Repository Info
- VCS: Gitea
- Server: https://code.example.io
- Owner: my-team
- Repository: backend-api
## Pull Request Context
- PR: #123
- Branch: feature/add-auth → main
- Commits: abc123def → xyz789abc
## Your Role
Review PR #123 for backend-api, comparing feature/add-auth against main.
```