Skip to content

Commit 196aa9d

Browse files
karlclementkarlclement
authored
Merge pull request #4 from sourcegraph/sayans/docs-update
2 parents 0bd3fa2 + 37d279a commit 196aa9d

File tree

4 files changed

+23
-164
lines changed

4 files changed

+23
-164
lines changed

‎.env.example‎

Lines changed: 3 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,17 @@
11
# GitHub App Configuration
22
GITHUB_APP_ID=your_github_app_id
33
GITHUB_APP_NAME=your-app-name
4-
GITHUB_APP_CLIENT_ID=your_github_app_client_id
5-
GITHUB_APP_CLIENT_SECRET=your_github_app_client_secret
4+
# Either GITHUB_APP_PRIVATE_KEY or GITHUB_APP_PRIVATE_KEY_PATH
65
GITHUB_APP_PRIVATE_KEY=your_github_app_private_key_base64_encoded
76
GITHUB_APP_PRIVATE_KEY_PATH=./private-key.pem
87
GITHUB_WEBHOOK_SECRET=your_webhook_secret
9-
GITHUB_REDIRECT_URI=http://localhost:5053/github/callback
108
GITHUB_BASE_URL=https://github.com
119
GITHUB_APP_CWD=/Users/username/project/your-repo
1210

13-
# MCP Configuration
14-
MCP_AUTH_TOKEN=your_mcp_secret
15-
CRA_PUBLIC_URL=https://ngrok-your-url.app
16-
1711
# Server Configuration
1812
APP_BASE_URL=https://ngrok-your-url.app
19-
SERVER_PORT=5053
20-
SERVER_DEBUG=true
13+
PORT=5053
14+
DEBUG=false
2115

2216
# Amp Configuration
23-
AMP_TIMEOUT=300
2417
AMP_SERVER_URL=https://ampcode.com

‎README.md‎

Lines changed: 15 additions & 104 deletions
Original file line numberDiff line numberDiff line change
@@ -10,14 +10,13 @@ A GitHub App for automated code reviews using Hono.js and Amp.
1010
- **Code Review**: AI-powered code analysis and feedback
1111
- **Check Runs**: Integration with GitHub's check runs API for status reporting
1212
- **MCP Server**: Model Context Protocol server for AI agent integration
13-
- **Dashboard**: Web interface for installation management
1413

1514
## Quick Start
1615

1716
1. **Clone and Install**
1817
```bash
1918
cd cra-github
20-
npm install
19+
pnpm install
2120
```
2221

2322
2. **Environment Setup**
@@ -27,14 +26,13 @@ A GitHub App for automated code reviews using Hono.js and Amp.
2726

2827
3. **Start Development Server**
2928
```bash
30-
npm run dev
29+
pnpm run dev
3130
```
3231

3332
4. **Install the App**
3433
- Visit `{APP_BASE_URL}/github/install` (e.g., `https://your-ngrok-url.app/github/install`)
3534
- Follow the GitHub App installation flow
3635
- Select repositories to enable code reviews
37-
- Access dashboard at `{APP_BASE_URL}/github/dashboard/{installationId}`
3836

3937
## Configuration
4038

@@ -47,64 +45,13 @@ A GitHub App for automated code reviews using Hono.js and Amp.
4745
- Repository: Contents (Read)
4846
- Repository: Metadata (Read)
4947
3. **Configure webhook settings:**
50-
- Webhook URL: `https://your-domain.com/github/webhook` (use your CRA_PUBLIC_URL)
48+
- Webhook URL: `https://your-domain.com/github/webhook` (use your APP_BASE_URL)
5149
- Subscribe to: Pull request events and Installation events
5250
4. **Generate and download a private key** from the app settings page
5351

5452
### Environment Variables
5553

56-
#### GitHub App Configuration (Required)
57-
```env
58-
# GitHub App ID (found in app settings)
59-
GITHUB_APP_ID=your_github_app_id
60-
61-
# GitHub App name (used in installation URL)
62-
GITHUB_APP_NAME=your-app-name
63-
64-
# GitHub App Client ID and Secret
65-
GITHUB_APP_CLIENT_ID=your_github_app_client_id
66-
GITHUB_APP_CLIENT_SECRET=your_github_app_client_secret
67-
68-
# Private Key Setup (choose one option)
69-
# Option 1: Private key file path
70-
GITHUB_APP_PRIVATE_KEY_PATH=./private-key.pem
71-
72-
# Option 2: Private key as environment variable (base64 encoded)
73-
GITHUB_APP_PRIVATE_KEY=your_github_app_private_key_base64_encoded
74-
75-
# Webhook and redirect configuration
76-
GITHUB_WEBHOOK_SECRET=your_webhook_secret
77-
GITHUB_REDIRECT_URI=http://localhost:5053/github/callback
78-
GITHUB_BASE_URL=https://github.com
79-
80-
# Working directory for the app (used by MCP server)
81-
GITHUB_APP_CWD=/Users/username/project/your-repo
82-
```
83-
84-
#### Public URL Configuration
85-
```env
86-
# Public URL for webhooks (use ngrok or similar for development)
87-
CRA_PUBLIC_URL=https://ngrok-your-url.app
88-
```
89-
90-
#### Server Configuration
91-
```env
92-
# Base URL for the application
93-
APP_BASE_URL=https://ngrok-your-url.app
94-
95-
# Server settings
96-
SERVER_PORT=5053
97-
SERVER_DEBUG=true
98-
```
99-
100-
#### Amp Configuration
101-
```env
102-
# Amp timeout (in seconds)
103-
AMP_TIMEOUT=300
104-
105-
# Amp server URL (use ampcode.com for hosted service)
106-
AMP_SERVER_URL=https://ampcode.com
107-
```
54+
Copy `.env.example` to `.env` and configure the required values.
10855

10956
### Private Key Setup
11057

@@ -124,48 +71,21 @@ The GitHub App requires a private key for authentication. You have two options:
12471
2. Set the result as `GITHUB_APP_PRIVATE_KEY` in your environment
12572
3. The application will automatically decode and format the key
12673

127-
**Security Notes:**
128-
- Never commit private keys to version control
129-
- Use secure secret management in production
130-
- Restrict file permissions: `chmod 600 private-key.pem`
131-
13274
### Configuration File (config.yml)
13375

134-
The app uses a `config.yml` file for core configuration including the AI system prompt and tool definitions. This file contains:
135-
136-
#### Key Configuration Sections:
137-
- **GitHub settings**: API endpoints, bot username, check run names
138-
- **Queue configuration**: Worker limits and retry settings
139-
- **Diff processing**: Chunk size limits for large diffs
140-
- **Amp integration**: Command settings and MCP server configuration
141-
- **System prompt**: The complete AI prompt template for code reviews
142-
- **Tool definitions**: Available MCP tools and their usage instructions
76+
Contains GitHub settings, queue configuration, server settings, Amp integration, and the AI review prompt. Environment variables are interpolated using `${VARIABLE_NAME}` syntax.
14377

144-
#### Important Notes:
145-
- The system prompt in `config.yml` defines how the AI reviews code
146-
- Tool definitions specify which GitHub operations are available to the AI
147-
- Environment variables are interpolated using `${VARIABLE_NAME}` syntax
148-
- Modify the prompt template to customize review behavior and focus areas
149-
- The configuration supports both development and production deployment modes
150-
151-
**Example customization:**
152-
To adjust review focus, modify the `prompt_template` section in `config.yml` to emphasize specific areas like security, performance, or coding standards.
78+
To customize review behavior, modify the `prompt_template` section.
15379

15480
## API Endpoints
15581

156-
### Core Endpoints
15782
- `GET /` - Service information
15883
- `GET /health` - Health check
159-
- `GET /queue/status` - Queue status information
84+
- `GET /queue/status` - Queue status information
16085
- `GET /jobs/:jobId` - Job status information
161-
- `POST /test/review` - Test endpoint for review functionality
162-
163-
### GitHub App Endpoints
16486
- `POST /github/webhook` - GitHub webhook endpoint
16587
- `GET /github/install` - Start GitHub App installation
16688
- `GET /github/callback` - GitHub App installation callback
167-
- `GET /github/dashboard/:installationId` - Installation dashboard
168-
16989

17090

17191
## Development
@@ -178,7 +98,7 @@ For development, you'll need to expose your local server to the internet for Git
17898

17999
2. **Start your local server**:
180100
```bash
181-
npm run dev
101+
pnpm run dev
182102
```
183103

184104
3. **Expose with ngrok** (in a separate terminal):
@@ -188,46 +108,38 @@ For development, you'll need to expose your local server to the internet for Git
188108

189109
4. **Update your environment**:
190110
- Copy the ngrok URL (e.g., `https://abc123.ngrok.io`)
191-
- Update `CRA_PUBLIC_URL` and `APP_BASE_URL` in your `.env` file
111+
- Update `APP_BASE_URL` in your `.env` file
192112
- Update your GitHub App webhook URL to `{your-ngrok-url}/github/webhook`
193113

194114
### Build
195115
```bash
196-
npm run build
116+
pnpm run build
197117
```
198118

199119
### Type Check
200120
```bash
201-
npm run type-check
121+
pnpm run type-check
202122
```
203123

204124
### Lint
205125
```bash
206-
npm run lint
126+
pnpm run lint
207127
```
208128

209129
### MCP Server
210130
Run the standalone MCP server:
211131
```bash
212-
npm run mcp
132+
pnpm run mcp
213133
```
214134

215135
Or build and run:
216136
```bash
217-
npm run mcp:build
137+
pnpm run mcp:build
218138
```
219139

220140
## MCP Integration
221141

222-
The app includes a Model Context Protocol (MCP) server that exposes GitHub operations as tools for Amp Agent.
223-
224-
### Available MCP Tools
225-
- `leave_general_comment` - Leave general comments on pull requests
226-
- `leave_inline_comment` - Leave inline comments on specific lines
227-
- `get_pr_comments` - Get all comments on a pull request
228-
229-
### Usage with AI Agents
230-
The MCP server runs as a standalone stdio server. See [`src/mcp/README.md`](src/mcp/README.md) for detailed configuration and usage instructions.
142+
The app includes a Model Context Protocol (MCP) server that exposes GitHub operations as tools for Amp Agent. See [`src/mcp/README.md`](src/mcp/README.md) for details.
231143

232144
## Architecture
233145

@@ -237,7 +149,6 @@ The MCP server runs as a standalone stdio server. See [`src/mcp/README.md`](src/
237149
- **Job Queue**: Background processing for code reviews
238150
- **Amp**: AI-powered code analysis engine
239151
- **MCP Server**: Model Context Protocol server for AI agent integration
240-
- **Installation Management**: Persistent storage for GitHub App installations
241152

242153
## License
243154

‎config.yml‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,13 @@
11
github:
22
base_url: "https://api.github.com"
33
check_name: "Amp Code Review"
4+
webhook_secret: "${GITHUB_WEBHOOK_SECRET}"
45

56
queue:
67
max_workers: 20
78
max_queue_size: 100
89
retry_after_seconds: 60
910

10-
11-
1211
server:
1312
port: "${PORT:-5053}"
1413
debug: "${DEBUG:-false}"

‎src/mcp/README.md‎

Lines changed: 4 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -7,57 +7,30 @@ This directory contains the Model Context Protocol (MCP) server implementation f
77
### 1. `leave_general_comment`
88
Leave general comments on pull requests.
99

10-
**Parameters:**
11-
- `message` (string, required): The comment message
12-
- `owner` (string, required): Repository owner
13-
- `repo` (string, required): Repository name
14-
- `pr_number` (number, required): Pull request number
15-
1610
### 2. `leave_inline_comment`
17-
Leave inline comments on specific lines in pull requests.
18-
19-
**Parameters:**
20-
- `message` (string, required): The comment message
21-
- `owner` (string, required): Repository owner
22-
- `repo` (string, required): Repository name
23-
- `pr_number` (number, required): Pull request number
24-
- `path` (string, required): File path for the inline comment
25-
- `line` (number, required): Line number for the inline comment
11+
Leave inline comments on specific lines in pull requests. Supports optional `suggested_fix` parameter for code suggestions.
2612

2713
### 3. `get_pr_comments`
2814
Get all comments on a pull request.
2915

30-
**Parameters:**
31-
- `owner` (string, required): Repository owner
32-
- `repo` (string, required): Repository name
33-
- `pr_number` (number, required): Pull request number
34-
3516
## Usage
3617

3718
### STDIO Server
3819

3920
Run the standalone MCP server for direct stdio communication:
4021

4122
```bash
42-
npm run mcp
23+
pnpm run mcp
4324
```
4425

4526
Or build and run:
4627
```bash
47-
npm run mcp:build
28+
pnpm run mcp:build
4829
```
4930

5031
## Configuration
5132

52-
The server uses the same configuration as the main application. Make sure your `config.yml` and environment variables are properly set:
53-
54-
### Environment Variables
55-
- `GITHUB_APP_ID` - GitHub App ID
56-
- `GITHUB_APP_PRIVATE_KEY` or `GITHUB_APP_PRIVATE_KEY_PATH` - GitHub App private key
57-
- `GITHUB_BASE_URL` - GitHub API URL (default: https://api.github.com)
58-
59-
### GitHub App Integration
60-
The MCP server works with GitHub App installations for authentication. When accessing repositories, it uses the GitHub App's installation tokens rather than personal access tokens.
33+
Uses the same configuration as the main application. Requires GitHub App credentials for authentication.
6134

6235
## Integration with AI Agents
6336

@@ -80,25 +53,8 @@ amp:
8053
8154
This allows Amp to automatically use the GitHub MCP tools during code reviews.
8255
83-
### Example Usage in Prompts
84-
85-
```
86-
You have access to GitHub tools. To review a pull request:
87-
88-
1. Use get_pr_comments to see existing feedback
89-
2. Review the code changes
90-
3. Use leave_inline_comment to add specific feedback
91-
4. Use leave_general_comment for overall observations
92-
93-
Owner: octocat
94-
Repo: Hello-World
95-
PR Number: 123
96-
```
97-
9856
### Code Review Workflow
9957
100-
The tools are designed to work together in a typical code review workflow:
101-
10258
1. **Check Existing Feedback**: `get_pr_comments` to see what's already been discussed
10359
2. **Leave Feedback**:
10460
- `leave_inline_comment` for specific line-level issues

0 commit comments

Comments
 (0)