Skip to content

Commit 4f8f249

Browse files
efraespadaefraespada
committed
feature-296-bugbot-autofix: Enhance Bugbot documentation by adding new sections for Detection, Autofix, Do User Request, Configuration, and How It Works. Update existing content for clarity and accuracy. Modify branch_repository.d.ts to reorder status types for consistency.
1 parent e211aeb commit 4f8f249

9 files changed

Lines changed: 855 additions & 100 deletions

File tree

‎build/github_action/src/data/repository/branch_repository.d.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ export declare class BranchRepository {
3333
totalCommits: number;
3434
files: {
3535
filename: string;
36-
status: "modified" | "added" | "removed" | "renamed" | "copied" | "changed" | "unchanged";
36+
status: "added" | "removed" | "modified" | "renamed" | "copied" | "changed" | "unchanged";
3737
additions: number;
3838
deletions: number;
3939
changes: number;

‎docs.json‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -177,6 +177,36 @@
177177
"title": "Overview",
178178
"href": "/bugbot",
179179
"icon": "bug"
180+
},
181+
{
182+
"title": "Detection",
183+
"href": "/bugbot/detection",
184+
"icon": "search"
185+
},
186+
{
187+
"title": "Autofix",
188+
"href": "/bugbot/autofix",
189+
"icon": "wrench"
190+
},
191+
{
192+
"title": "Do user request",
193+
"href": "/bugbot/do-user-request",
194+
"icon": "edit"
195+
},
196+
{
197+
"title": "Configuration",
198+
"href": "/bugbot/configuration",
199+
"icon": "gear"
200+
},
201+
{
202+
"title": "How it works",
203+
"href": "/bugbot/how-it-works",
204+
"icon": "cpu"
205+
},
206+
{
207+
"title": "Examples",
208+
"href": "/bugbot/examples",
209+
"icon": "file-code"
180210
}
181211
]
182212
},

‎docs/bugbot/autofix.mdx‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
---
2+
title: Autofix
3+
description: How to ask the bot to fix one or more Bugbot findings from an issue or PR comment.
4+
---
5+
6+
# Autofix
7+
8+
**Bugbot autofix** lets you ask the bot to **fix** one or more of the findings it previously reported. You write a **comment** on the issue or on the pull request (or reply in a review thread); OpenCode figures out **which** findings you mean and applies the fixes. The action then runs your **verify commands** (e.g. build, test, lint) and, if they pass, **commits and pushes** and marks those findings as resolved.
9+
10+
This page explains how to trigger autofix, who can do it, and what the action does under the hood.
11+
12+
---
13+
14+
## How to ask for a fix
15+
16+
### From the issue
17+
18+
Add a **comment** on the issue that references the findings you want fixed. OpenCode receives your comment plus the list of **unresolved findings** (id, title, short description) and returns whether it’s a fix request and which finding ids to fix.
19+
20+
**Example phrases (English):**
21+
22+
- “fix it”
23+
- “fix this”
24+
- “fix all”
25+
- “fix the first one”
26+
- “fix finding abc-123”
27+
- “please fix the null reference and the off-by-one”
28+
29+
**Example phrases (Spanish):**
30+
31+
- “arregla”
32+
- “arregla este”
33+
- “arregla todos”
34+
- “fix it” (also understood)
35+
36+
You don’t have to use exact wording; the Plan agent interprets intent. Be clear when you want only **some** findings (e.g. “fix the first two” or “fix the one about the login handler”).
37+
38+
**Important:** On **issue comments**, the action needs an **open pull request** that references the issue so it can determine which **branch** to checkout and push to. If there is no such PR, autofix is skipped (the action cannot push without a branch). See [Troubleshooting → Bugbot autofix](/troubleshooting#bugbot-autofix).
39+
40+
### From the pull request
41+
42+
You can trigger autofix from the PR in two ways:
43+
44+
1. **Reply in a review thread** — Reply to the **review comment** that contains the finding. The action sends your reply plus the **parent comment** (the finding text) to OpenCode so it can match the finding and run the fix.
45+
2. **Comment on the PR** — Add a **general comment** on the PR (e.g. “fix all” or “fix the one about X”). Same as on the issue: OpenCode gets the list of unresolved findings and your comment and returns target finding ids.
46+
47+
In both cases, the action runs on the PR’s **head branch** (it already has the branch from the event), so no extra “resolve branch from issue” step is needed.
48+
49+
---
50+
51+
## Permissions
52+
53+
Only **certain users** can trigger file-modifying actions (autofix and [do user request](/bugbot/do-user-request)):
54+
55+
- **Organization repositories:** The comment author must be a **member of the organization** (checked via GitHub’s `orgs.checkMembershipForUser`). If the author is not a member, the action does **not** run autofix; it can still run **Think** and reply with an answer.
56+
- **User (personal) repositories:** Only the **repository owner** can trigger autofix. Other users get a Think response only.
57+
58+
This avoids random contributors or external users pushing commits via comments. There is no separate “Bugbot role”; the same rule applies to both autofix and do-user-request.
59+
60+
---
61+
62+
## Workflow permissions
63+
64+
The action must be able to **commit and push** to the branch. Your workflow that runs on **`issue_comment`** or **`pull_request_review_comment`** must grant:
65+
66+
```yaml
67+
permissions:
68+
contents: write
69+
```
70+
71+
Without `contents: write`, the action cannot push. Detection (and posting findings) does not require this; only **autofix** and **do-user-request** do.
72+
73+
Example: see [Examples → Issue comment workflow](/bugbot/examples#issue-comment-workflow-for-autofix).
74+
75+
---
76+
77+
## Verify commands
78+
79+
After OpenCode applies the fixes in its workspace, the action runs **verify commands** in the runner (e.g. build, test, lint). These are configured with **`bugbot-fix-verify-commands`** (comma-separated). For example:
80+
81+
```yaml
82+
bugbot-fix-verify-commands: "npm run build, npm test, npm run lint"
83+
```
84+
85+
- If **all** commands succeed, the action runs `git add`, **commit**, and **push** with a message like `fix(#123): bugbot autofix - resolve finding-1, finding-2`.
86+
- If **any** command fails, the action **does not commit**. No push happens, and the findings are not marked as resolved.
87+
88+
So verify commands act as a gate: only passing runs produce a commit. If you leave `bugbot-fix-verify-commands` empty, only OpenCode’s own run is used (the action may still commit if there are file changes). See [Configuration](/bugbot/configuration#bugbot-fix-verify-commands).
89+
90+
---
91+
92+
## What happens after a successful fix
93+
94+
1. OpenCode **Build** agent applies the code changes in its workspace.
95+
2. The action runs the **verify commands** in the runner; if any fails, it stops.
96+
3. The action runs **git add**, **commit** (message: `fix(#N): bugbot autofix - resolve <finding ids>`), and **push** to the branch.
97+
4. The action **marks** the fixed findings as **resolved**: it updates the corresponding issue and PR comments (hidden marker set to `resolved: true`) and, on the PR, **resolves the review threads** for those comments.
98+
99+
So the next time detection runs (e.g. on the next push), OpenCode will see those findings as resolved and not suggest them again.
100+
101+
---
102+
103+
## Troubleshooting
104+
105+
- **Bot didn’t run autofix:** Check that OpenCode is configured, the comment is interpreted as a fix request (e.g. “fix it”, “fix all”), and there is at least one **unresolved** finding. On **issue comments**, ensure there is an **open PR** that references the issue so the action can resolve the branch. See [Troubleshooting → Bugbot autofix](/troubleshooting#bugbot-autofix).
106+
- **Commit not made:** Verify commands run after the fix; if any fails, no commit is made. If OpenCode didn’t change any files, there’s nothing to commit. If push failed (e.g. conflict or missing `contents: write`), check workflow permissions and token scope.
107+
108+
---
109+
110+
## Next steps
111+
112+
- **[Do user request](/bugbot/do-user-request)** — Ask for general code changes (not tied to a specific finding).
113+
- **[Configuration](/bugbot/configuration)** — `bugbot-fix-verify-commands` and related inputs.
114+
- **[Examples](/bugbot/examples)** — Comment examples and workflow snippets.

‎docs/bugbot/configuration.mdx‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
---
2+
title: Configuration
3+
description: All Bugbot-related action inputs: severity, comment limit, verify commands, and ignore files.
4+
---
5+
6+
# Configuration
7+
8+
This page lists every **Bugbot-related** input: what it does, default value, and example usage. For the full list of Copilot inputs (branches, labels, projects, etc.), see [Configuration](/configuration).
9+
10+
---
11+
12+
## OpenCode (required for Bugbot)
13+
14+
Bugbot depends on OpenCode for both **detection** (Plan agent) and **autofix / do-user-request** (Build agent). These inputs are shared with other AI features (progress, Think, AI PR description).
15+
16+
| Input | Default | Description |
17+
|-------|---------|-------------|
18+
| **`opencode-server-url`** | `http://localhost:4096` | URL of the OpenCode server. The runner must be able to reach it (e.g. same job if you use `opencode-start-server: true`). |
19+
| **`opencode-model`** | `opencode/kimi-k2.5-free` | Model in `provider/model` format (e.g. `anthropic/claude-3-5-sonnet`, `openai/gpt-4o-mini`). |
20+
| **`opencode-start-server`** | `true` | If `true`, the action starts an OpenCode server at job start and stops it at job end. Requires provider API keys (e.g. `OPENAI_API_KEY`) passed as env. If you run OpenCode yourself, set to `false` and pass `opencode-server-url`. |
21+
22+
Without a valid `opencode-server-url` and `opencode-model`, Bugbot **detection** is skipped (no findings posted). **Autofix** and **do-user-request** also require OpenCode and a running server (or `opencode-start-server: true`) so the Build agent can apply changes in the workspace.
23+
24+
---
25+
26+
## bugbot-severity
27+
28+
**Default:** `low`
29+
30+
**Description:** Minimum severity for findings to be **published** as comments on the issue and PR. Findings with severity **below** this threshold are filtered out before publishing.
31+
32+
| Value | Findings published |
33+
|-------|---------------------|
34+
| `info` | info, low, medium, high |
35+
| `low` | low, medium, high |
36+
| `medium` | medium, high |
37+
| `high` | high only |
38+
39+
**Example:**
40+
41+
```yaml
42+
# Only report medium and high (skip low and info)
43+
bugbot-severity: "medium"
44+
```
45+
46+
```yaml
47+
# Report everything including info
48+
bugbot-severity: "info"
49+
```
50+
51+
---
52+
53+
## bugbot-comment-limit
54+
55+
**Default:** `20`
56+
57+
**Description:** Maximum number of findings to publish as **individual** comments on the issue and PR. If OpenCode returns more findings (after severity and ignore filters), only the first N are posted one per comment; the rest are summarized in a **single overflow comment** on the issue (e.g. “X additional findings were not posted; consider reviewing the branch locally”).
58+
59+
The value is clamped between **1** and **200** (or your docs’ stated range). Use a higher limit if you want more findings visible at the cost of more comments.
60+
61+
**Example:**
62+
63+
```yaml
64+
# Default: up to 20 individual comments + 1 overflow if needed
65+
bugbot-comment-limit: "20"
66+
67+
# Stricter: only 10 individual comments
68+
bugbot-comment-limit: "10"
69+
70+
# Allow up to 50 individual comments
71+
bugbot-comment-limit: "50"
72+
```
73+
74+
---
75+
76+
## bugbot-fix-verify-commands
77+
78+
**Default:** `""` (empty)
79+
80+
**Description:** Comma-separated list of **commands** to run **after** OpenCode applies changes (autofix or do-user-request) and **before** the action commits and pushes. Typically: build, test, lint. If **any** command fails, the action **does not commit**; no push happens and findings are not marked as resolved.
81+
82+
- Commands are parsed (e.g. with shell-quote) and run in the runner; there is a **maximum of 20** commands.
83+
- If left **empty**, only OpenCode’s own execution is used; the action may still commit if there are file changes.
84+
85+
**Example:**
86+
87+
```yaml
88+
# Run build, test, and lint before committing
89+
bugbot-fix-verify-commands: "npm run build, npm test, npm run lint"
90+
```
91+
92+
```yaml
93+
# Single command
94+
bugbot-fix-verify-commands: "npm test"
95+
```
96+
97+
```yaml
98+
# From a repo/organization variable (recommended for secrets or env-specific commands)
99+
bugbot-fix-verify-commands: ${{ vars.BUGBOT_AUTOFIX_VERIFY_COMMANDS }}
100+
```
101+
102+
Use this in workflows that run on **`issue_comment`** or **`pull_request_review_comment`** so autofix and do-user-request only commit when your checks pass.
103+
104+
---
105+
106+
## ai-ignore-files
107+
108+
**Default:** `""` (empty)
109+
110+
**Description:** Comma-separated list of **paths or patterns** to **exclude** from AI operations that analyze file content or paths. For Bugbot:
111+
112+
- **Detection:** These paths are passed to OpenCode in the prompt (“do not report findings in files matching …”) and findings in matching files are **filtered out** before publishing.
113+
- **Autofix / do-user-request:** The ignore list is not used to restrict which files the Build agent can edit; it mainly affects **detection** and reporting.
114+
115+
Common use: exclude generated code, vendored deps, or noisy directories.
116+
117+
**Example:**
118+
119+
```yaml
120+
# Ignore build output and lockfiles
121+
ai-ignore-files: "build/*, dist/*, package-lock.json"
122+
```
123+
124+
```yaml
125+
# Ignore specific dirs and patterns
126+
ai-ignore-files: "**/node_modules/**, **/vendor/**, *.min.js"
127+
```
128+
129+
---
130+
131+
## Summary table
132+
133+
| Input | Default | Used by |
134+
|-------|---------|---------|
135+
| `opencode-server-url` | `http://localhost:4096` | Detection, autofix, do-user-request |
136+
| `opencode-model` | `opencode/kimi-k2.5-free` | Detection, autofix, do-user-request |
137+
| `opencode-start-server` | `true` | All AI features |
138+
| `bugbot-severity` | `low` | Detection (filter before publish) |
139+
| `bugbot-comment-limit` | `20` | Detection (max individual comments) |
140+
| `bugbot-fix-verify-commands` | `""` | Autofix, do-user-request (before commit) |
141+
| `ai-ignore-files` | `""` | Detection (exclude paths from findings) |
142+
143+
---
144+
145+
## Next steps
146+
147+
- **[Detection](/bugbot/detection)** — How severity and comment limit affect published findings.
148+
- **[Autofix](/bugbot/autofix)** — How verify commands gate commits.
149+
- **[Configuration](/configuration)** — Full Copilot configuration reference.

0 commit comments

Comments
 (0)