# Forge Integration Setup
> **Experimental / Unsupported:** Git forge integration is experimental and
> unofficial. It is provided as-is, without guarantees of stability or
> correctness. Use it at your own risk. Breaking changes may occur without
> notice, and community support is best-effort only.
This guide explains how to integrate Sashiko with Git forges (GitHub, GitLab, etc.) for automatic code review.
## Overview
Sashiko can integrate with Git forges to automatically review Pull Requests (PRs) or Merge Requests (MRs) when they are opened or updated. This enables automated code review workflows for your development teams.
## Supported Forges
Currently supported:
- **GitHub** - Full webhook integration ([GitHub Setup Guide](GITHUB_SETUP.md))
- **GitLab** - Full webhook integration ([GitLab Setup Guide](GITLAB_SETUP.md))
## Forge Requirements
For a Git forge to be compatible with Sashiko, it must support:
### 1. Webhook Delivery
**Required capabilities:**
- HTTP/HTTPS webhook delivery to external endpoints
- JSON payload format
- Custom headers (for event identification)
- Configurable event triggers (PR/MR events)
**Event triggers needed:**
- Pull/Merge request opened
- Pull/Merge request updated (new commits)
- Pull/Merge request reopened
**Optional but recommended:**
- Webhook secret/signature validation
- Webhook delivery retry logic
- Webhook delivery status/logs
### 2. API Access
**Required endpoints:**
- Fetch PR/MR details by ID
- Retrieve commit information
- Access diff/patch data
**Authentication:**
- Public repository access (no auth for public repos)
- Token-based authentication (for private repos)
- Rate limiting information
**Optional but useful:**
- Post comments on PRs/MRs
- Update PR/MR status
- Create review summaries
### 3. Git Repository Access
**Required:**
- HTTP(S) clone URLs accessible from Sashiko server
- Support for standard Git protocol
- Ability to fetch specific commit ranges
**Authentication options:**
- Anonymous access for public repos
- SSH key authentication
- HTTP(S) token authentication
- Deploy keys
### 4. Webhook Payload Requirements
The webhook must provide:
**Minimal required fields:**
```json
{
"pr_or_mr": {
"id": "<unique identifier>",
"title": "<PR/MR title>",
"base_commit": "<base SHA>",
"head_commit": "<head SHA>",
"url": "<web URL to PR/MR>"
},
"repository": {
"clone_url": "<git clone URL>"
}
}
```
**Recommended additional fields:**
- Source branch name
- Target branch name
- Author information
- Commit count
- Changed files list
- PR/MR state (open, closed, merged)
## General Configuration
### Enable Forge Integration
Edit `Settings.toml`:
```toml
[forge]
# Enable to accept webhooks from GitHub, GitLab, etc.
enabled = true
# If enabled, you can optionally disable the NNTP/mailing-list ingestor.
# By default, running both is disabled to prevent duplicate reviews if a
# patch from a PR is also sent to a mailing list.
# Set to 'false' if you need to monitor both mailing lists and forges.
disable_nntp = true
# Global Config: Map file paths to subsystems for targeted reviews (Optional)
[subsystems]
mapping = [
{ pattern = ".*drivers/.*", name = "Drivers" },
{ pattern = ".*net/.*", name = "Networking" },
{ pattern = ".*fs/.*", name = "Filesystems" },
{ pattern = ".*mm/.*", name = "Memory Management" },
]
```
### Server Configuration
Ensure your server is configured to accept webhooks:
```toml
[server]
host = "127.0.0.1" # Listen address
port = 8080 # Port for webhook endpoint
```
**Security:** Sashiko supports webhook signature verification via HMAC-SHA256
(GitHub and GitLab 19.0+ signing tokens) and legacy secret tokens. When
`webhook_secret` is configured, non-localhost requests are authenticated
without requiring `--enable-unsafe-all-submit`. See the
[Webhook Security Guide](WEBHOOK_SECURITY.md) for setup instructions and
production deployment recommendations.
### Git Configuration
Configure the reference repository:
```toml
[git]
repository_path = "/path/to/kernel/repo"
```
**Note:** The repository must be accessible and contain the commits referenced in webhooks.
### Review Configuration
```toml
[review]
concurrency = 20 # Parallel review capacity
worktree_dir = "review_trees" # Temporary worktrees
timeout_seconds = 7200 # 2 hours per review
```
## Webhook Endpoints
Sashiko provides the following webhook endpoints:
- **GitHub**: `http://your-server:8080/api/webhook/github`
- **GitLab**: `http://your-server:8080/api/webhook/gitlab`
### Expected HTTP Headers
**GitHub:**
```
X-GitHub-Event: pull_request
Content-Type: application/json
```
**GitLab:**
```
X-Gitlab-Event: Merge Request Hook
Content-Type: application/json
```
### Response Codes
- `200 OK` - Webhook accepted, review queued
- `400 Bad Request` - Invalid payload or missing required fields
- `403 Forbidden` - Forge integration disabled
- `500 Internal Server Error` - Server error processing webhook
## Testing Integration
### 1. Test with Synthetic Webhook
Use the provided test scripts to verify the endpoint:
**GitHub:**
```bash
./scripts/test_github_webhook.sh
```
**GitLab:**
```bash
./scripts/test_gitlab_webhook.sh
```
### 2. Test with Real PR/MR
Trigger a review for a specific PR/MR:
**GitHub:**
```bash
./scripts/trigger_github_pr_review.sh owner/repo 123
```
**GitLab:**
```bash
./scripts/trigger_gitlab_mr_review.sh 123
```
### 3. Verify Review Queue
Check the web UI to confirm the review was queued:
```
http://localhost:8080/
```
Look for:
- Review in "Pending" or "In Progress" state
- Correct PR/MR number and title
- Expected commit range
## Implementing Support for New Forges
To add support for a new Git forge, you need to:
### 1. Understand the Forge's Webhook Format
Document:
- Webhook payload structure
- HTTP headers used for event identification
- Available event types and actions
- Authentication/signature mechanism
### 2. Create a ForgeProvider Implementation
Implement the `ForgeProvider` trait in Rust:
```rust
pub trait ForgeProvider {
/// Parse the webhook payload and extract review information
fn parse_webhook(&self, headers: &HeaderMap, body: &[u8])
-> Result<WebhookEvent, Error>;
/// Optional: Post review results back to the forge
fn post_review(&self, pr_id: &str, review: &Review)
-> Result<(), Error>;
}
```
### 3. Register the Webhook Handler
Add a new endpoint in the API router:
```rust
// In src/api.rs or equivalent
app.route("/api/webhook/yourforge", post(handle_yourforge_webhook))
```
### 4. Add Configuration
Extend `Settings.toml` if forge-specific config is needed:
```toml
[forge.yourforge]
api_token = "optional-token"
api_endpoint = "https://api.yourforge.com"
```
### 5. Create Documentation and Scripts
- Write setup guide (e.g., `docs/YOURFORGE_SETUP.md`)
- Create test script (`scripts/test_yourforge_webhook.sh`)
- Create trigger script (`scripts/trigger_yourforge_review.sh`)
## Troubleshooting
### Webhook Not Received
**Symptoms:** No log entries when PR/MR is opened
**Check:**
- Server is running: `curl http://localhost:8080/`
- Firewall allows inbound on configured port
- Webhook URL is accessible from forge servers
- Forge shows successful delivery in webhook logs
**Solutions:**
- Use ngrok/tunneling for local testing
- Check server logs: `RUST_LOG=debug cargo run`
- Verify webhook URL in forge configuration
### Webhook Rejected (403 Forbidden)
**Symptoms:** Forge shows 403 response
**Cause:** Forge integration disabled or security restrictions
**Solutions:**
- Set `forge.enabled = true` in Settings.toml
- Restart Sashiko daemon
- Use `--enable-unsafe-all-submit` for testing (not production)
### Review Not Starting
**Symptoms:** Webhook accepted but review doesn't begin
**Check:**
- LLM API key configured: `echo $LLM_API_KEY`
- Git repository contains referenced commits
- Sashiko has network access to clone repository
- Disk space available in worktree directory
**Solutions:**
- Check logs for specific errors
- Verify git repository accessibility
- Test LLM provider connection
- Ensure commits exist in configured repository
### Commits Not Found
**Symptoms:** Review fails with "commit not found" error
**Causes:**
- Repository mismatch (webhook references different repo)
- Commits not yet fetched to local repository
- Shallow clone missing history
**Solutions:**
- Ensure `git.repository_path` points to correct repo
- Run `git fetch --all` in repository
- Use full clone (not shallow) for reference repository
## Security Best Practices
Sashiko supports webhook signature verification. For complete setup
instructions, deployment topologies, reverse proxy examples, and a
production checklist, see the [Webhook Security Guide](WEBHOOK_SECURITY.md).
## Forge Comparison
| Webhook delivery | ✅ | ✅ | **Required** |
| JSON payloads | ✅ | ✅ | **Required** |
| Event filtering | ✅ | ✅ | **Required** |
| Webhook secrets | ✅ | ✅ | ✅ Implemented |
| Signature validation | ✅ | ✅ | ✅ Implemented |
| Delivery logs | ✅ | ✅ | Recommended |
| Public API | ✅ | ✅ | **Required** |
| Token auth | ✅ | ✅ | **Required** |
| SSH clone | ✅ | ✅ | **Required** |
| HTTPS clone | ✅ | ✅ | **Required** |
| Comment API | ✅ | ✅ | Optional |
| Status API | ✅ | ✅ | Optional |
## Related Documentation
- [GitHub Setup Guide](GITHUB_SETUP.md) - Detailed GitHub integration
- [GitLab Setup Guide](GITLAB_SETUP.md) - Detailed GitLab integration
- [README.md](../README.md) - Main project documentation
- [Settings.toml](../Settings.toml) - Configuration reference
## Getting Help
- **Mailing List:** sashiko@lists.linux.dev ([archive](https://lore.kernel.org/sashiko))
- **GitHub Issues:** [Report bugs or request features](https://github.com/sashiko-dev/sashiko/issues)
- **Community:** Join discussions about forge integration and feature requests