Skip to content

Commit bc3929e

Browse files
TimeToBuildBobTimeToBuildBob
authored
docs(bot): improve GitHub bot documentation (#938)
* docs(bot): improve GitHub bot documentation - Add quick start section with minimal setup - Document how the bot determines questions vs changes mode - Add configuration options table with all inputs - Include best practices for good/bad prompts - Add security considerations section - Add troubleshooting guide for common issues - Document local testing workflow - List limitations clearly - Reference examples in the wild Addresses #478 * fix(docs): correct Pygments lexer and cross-references in bot.md - Change ```txt to ```text (Pygments recognizes 'text' not 'txt') - Change cross-references from .md to .rst (matching actual file extensions) Fixes CI build failure with 7 warnings treated as errors. * fix(docs): use correct script path in local testing examples Address Greptile review: Change placeholder /path/to/github_bot.py to the correct scripts/github_bot.py relative to repo root.
1 parent c36e250 commit bc3929e

File tree

1 file changed

+160
-17
lines changed

1 file changed

+160
-17
lines changed

‎docs/bot.md‎

Lines changed: 160 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,11 @@
11
GitHub Bot
22
==========
33

4-
One way to run gptme is as a GitHub bot.
4+
The gptme GitHub bot lets you run gptme directly from GitHub issues and pull requests. Just comment `@gptme <your prompt>` and the bot will respond or make changes.
55

6-
The `gptme-bot` composite action is a GitHub Action that runs `gptme` in response to comments on GitHub issues or pull requests using the format `@gptme <prompt>`. It is designed to be used for tasks that gptme can perform with a one-shot prompt, such as answering questions, running commands and committing their results, creating files or making simple changes/additions (like write tests), and (potentially) automating code reviews.
6+
## Quick Start
77

8-
## Usage
9-
10-
To use the `gptme-bot` composite action in your repo, you need to create a GitHub Actions workflow file that triggers the action in response to comments on issues or pull requests.
11-
12-
Here is an example workflow file that triggers the action in response to issue comments:
8+
Add this workflow to your repository at `.github/workflows/gptme-bot.yml`:
139

1410
```yaml
1511
name: gptme-bot
@@ -24,21 +20,168 @@ jobs:
2420
run-bot:
2521
runs-on: ubuntu-latest
2622
steps:
27-
- name: Checkout
28-
uses: actions/checkout@v4
29-
30-
- name: run gptme-bot action
31-
uses: gptme/gptme/.github/actions/bot@master
23+
- uses: actions/checkout@v4
24+
- uses: gptme/gptme/.github/actions/bot@master
3225
with:
3326
openai_api_key: ${{ secrets.OPENAI_API_KEY }}
27+
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
3428
github_token: ${{ secrets.GITHUB_TOKEN }}
35-
allowlist: "erikbjare"
29+
allowlist: "your-username"
30+
```
31+
32+
Then comment `@gptme <prompt>` on any issue or PR!
33+
34+
## How It Works
35+
36+
The bot operates in two modes:
37+
38+
**Questions** - If you ask a question, the bot replies directly:
39+
```text
40+
@gptme What does this function do?
41+
@gptme Explain the architecture of this project
42+
@gptme How should I approach fixing issue #123?
43+
```
44+
45+
**Changes** - If you request changes, the bot:
46+
1. Checks out the appropriate branch (PR branch or creates new branch)
47+
2. Runs gptme with your prompt
48+
3. Commits any changes made
49+
4. Pushes and creates a PR (if on an issue) or pushes to PR branch (if on a PR)
50+
51+
```text
52+
@gptme Add tests for the utils module
53+
@gptme Fix the typo in README.md
54+
@gptme Implement the feature described in this issue
55+
```
56+
57+
The bot uses an LLM to determine which mode based on your prompt.
58+
59+
## Configuration Options
60+
61+
| Input | Description | Required | Default |
62+
|-------|-------------|----------|---------|
63+
| `openai_api_key` | OpenAI API key | No* | - |
64+
| `anthropic_api_key` | Anthropic API key | No* | - |
65+
| `model` | Model to use | No | `anthropic/claude-sonnet-4-20250514` |
66+
| `github_token` | GitHub token for API access | Yes | - |
67+
| `allowlist` | Comma-separated usernames allowed to trigger | Yes | `ErikBjare` |
68+
69+
\*At least one API key is required.
70+
71+
### Example with Custom Model
72+
73+
```yaml
74+
- uses: gptme/gptme/.github/actions/bot@master
75+
with:
76+
openai_api_key: ${{ secrets.OPENAI_API_KEY }}
77+
github_token: ${{ secrets.GITHUB_TOKEN }}
78+
allowlist: "user1,user2,user3"
79+
model: "openai/gpt-4o"
80+
```
81+
82+
## Best Practices
83+
84+
### Good Prompts
85+
86+
**For questions:**
87+
- Be specific about what you want explained
88+
- Reference files or functions by name
89+
- Ask about design decisions or alternatives
90+
91+
```text
92+
@gptme What does the `compress_context` function in context.py do?
93+
@gptme Why does this project use SQLite instead of PostgreSQL?
94+
```
95+
96+
**For changes:**
97+
- Be clear about what you want changed
98+
- Reference specific files or locations when possible
99+
- Break complex changes into smaller prompts
100+
101+
```text
102+
@gptme Add a docstring to the compress_context function
103+
@gptme Add type hints to all functions in utils.py
104+
@gptme Create a test file for the new feature in this PR
36105
```
37106

38-
The `gptme-bot` action will then run the `gptme` command-line tool with the command specified in the comment, and perform actions based on the output of the tool.
107+
### Prompts to Avoid
108+
109+
- Very complex multi-step changes (break them up)
110+
- Vague requests ("make this better")
111+
- Large refactors spanning many files
112+
113+
## Security Considerations
114+
115+
1. **Allowlist** - Only users on the allowlist can trigger the bot
116+
2. **Permissions** - The bot has `write-all` permissions, so protect your allowlist
117+
3. **API Keys** - Store API keys as repository secrets, never in code
118+
4. **Review Changes** - Always review bot-created PRs before merging
119+
120+
## Troubleshooting
121+
122+
### Bot doesn't respond
123+
124+
1. Check that the user is on the allowlist
125+
2. Verify the workflow is enabled (Actions tab)
126+
3. Check the workflow run logs for errors
127+
4. Ensure API keys are configured as secrets
128+
129+
### Bot creates wrong changes
130+
131+
1. Be more specific in your prompt
132+
2. Reference specific files and line numbers
133+
3. Break complex requests into smaller steps
134+
135+
### Authentication errors
136+
137+
1. Verify `GITHUB_TOKEN` has necessary permissions
138+
2. Check that API keys are valid and not expired
139+
3. Ensure secrets are accessible to the workflow
140+
141+
## Local Testing
142+
143+
You can test the bot locally before deploying:
144+
145+
```bash
146+
# Clone the repository
147+
git clone https://github.com/your-org/your-repo
148+
cd your-repo
149+
150+
# Test with a question
151+
GITHUB_TOKEN=your_token \
152+
GITHUB_REPOSITORY=your-org/your-repo \
153+
ANTHROPIC_API_KEY=your_key \
154+
python scripts/github_bot.py \
155+
--issue 123 \
156+
--comment-body "@gptme What is this project?" \
157+
--dry-run
158+
159+
# Test with changes
160+
GITHUB_TOKEN=your_token \
161+
GITHUB_REPOSITORY=your-org/your-repo \
162+
ANTHROPIC_API_KEY=your_key \
163+
python scripts/github_bot.py \
164+
--pr 456 \
165+
--comment-body "@gptme Fix the typo" \
166+
--workspace . \
167+
--dry-run
168+
```
169+
170+
## Limitations
171+
172+
- **One-shot execution** - The bot runs once per comment, no multi-turn conversation
173+
- **Timeout** - Commands time out after 2 minutes
174+
- **Context** - The bot has access to the issue/PR context but limited file context
175+
- **Complexity** - Works best for simple, well-defined tasks
176+
177+
## Examples in the Wild
39178

40-
If a question was asked, it will simply reply.
179+
The gptme project itself uses this bot. See examples:
180+
- [Original implementation issue #16](https://github.com/gptme/gptme/issues/16)
181+
- Search for "gptme-bot" in closed PRs to see bot-created changes
41182

42-
If a request was made it will check out the appropriate branch, install dependencies, run `gptme`, then commit and push any changes made. If the issue is a pull request, the bot will push changes directly to the pull request branch. If the issue is not a pull request, the bot will create a new pull request with the changes.
183+
## Related
43184

44-
The feature was initially introduced in [#16](https://github.com/gptme/gptme/issues/16).
185+
- [Automation](automation.rst) - Other ways to automate gptme
186+
- [Server](server.rst) - Running gptme as a service
187+
- [CLI Reference](cli.rst) - Command-line options

0 commit comments

Comments
 (0)