# Deployment Guide
This guide covers deploying the GitHub MCP Control Plane to Cloudflare Workers.
## Prerequisites
Before deploying, ensure you have:
- Node.js 18+ installed
- Wrangler CLI installed globally
- Cloudflare account with Workers enabled
- GitHub Personal Access Token with appropriate permissions
- (Optional) GitHub repository for workflow delegation
## Installation
### 1. Clone Repository
```bash
git clone <repository-url>
cd github-mcp-control-plane
```
### 2. Install Dependencies
```bash
npm install
```
### 3. Configure Wrangler
```bash
wrangler login
```
This will open a browser to authenticate with your Cloudflare account.
## Configuration
### 1. Update `wrangler.toml`
Edit `wrangler.toml` to configure your worker:
```toml
name = "github-mcp-control-plane"
main = "src/mcp/entrypoint.js"
compatibility_date = "2024-01-01"
node_compat = true
[[kv_namespaces]]
binding = "KV_RATE_LIMIT"
id = "your_kv_namespace_id"
preview_id = "your_preview_kv_namespace_id"
[vars]
ENVIRONMENT = "production"
LOG_LEVEL = "info"
MAX_BATCH_SIZE = "100"
RATE_LIMIT_WINDOW = "60"
RATE_LIMIT_MAX_REQUESTS = "100"
```
### 2. Create KV Namespace
```bash
# Create production KV namespace
wrangler kv:namespace create "RATE_LIMIT"
# Create preview KV namespace
wrangler kv:namespace create "RATE_LIMIT" --preview
```
Copy the IDs returned and update `wrangler.toml`.
### 3. Set Secrets
Set the required secrets for your worker:
```bash
# GitHub Personal Access Token
wrangler secret put GITHUB_TOKEN
# GitHub Webhook Secret (for workflow delegation)
wrangler secret put GITHUB_WEBHOOK_SECRET
# JWT Secret (minimum 32 characters)
wrangler secret put JWT_SECRET
# Encryption Key (minimum 32 characters)
wrangler secret put ENCRYPTION_KEY
```
### 4. Validate Configuration
```bash
npm run validate-config
```
This validates all configuration files for correctness.
## GitHub Token Permissions
Your GitHub Personal Access Token should have the following scopes:
### Read Operations
- `repo` - Full control of private repositories
- `read:org` - Read org and team membership
- `read:project` - Read project board access
### Write Operations
- `repo` - Full control of private repositories
- `write:org` - Manage organization membership
### Workflow Operations
- `repo` - Full control of private repositories
- `workflow` - Update GitHub Action workflows
**Recommended**: Create separate tokens for different environments (staging, production).
## Deployment
### Local Development
Start the local development server:
```bash
npm run dev
```
The worker will be available at `http://localhost:8787`.
### Deploy to Staging
```bash
wrangler deploy --env staging
```
### Deploy to Production
```bash
wrangler deploy
```
Or explicitly:
```bash
wrangler deploy --env production
```
## GitHub Actions Integration
For delegation of long-running tasks, configure GitHub Actions:
### 1. Add Workflow to Repository
Create `.github/workflows/execution-handler.yml` in your target repositories (or use the provided workflow).
### 2. Set Repository Secrets
In your repository settings, add the following secrets:
- `GITHUB_WEBHOOK_SECRET`: Webhook secret matching your worker configuration
### 3. Configure Worker URL
Update the workflow to use your deployed worker URL.
### 4. Test Workflow Trigger
```bash
curl -X POST \
-H "Authorization: Bearer <your-token>" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": "test-1",
"method": "trigger_workflow",
"params": {
"owner": "your-org",
"repo": "your-repo",
"workflowId": "execution-handler.yml",
"ref": "main"
}
}' \
https://your-worker-url.workers.dev
```
## Verification
### 1. Health Check
```bash
curl https://your-worker-url.workers.dev/health
```
Expected response:
```json
{
"status": "healthy",
"timestamp": "2024-01-01T00:00:00Z",
"version": "1.0.0"
}
```
### 2. Test Read Operation
```bash
curl -X POST \
-H "Authorization: Bearer <your-github-token>" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": "test-2",
"method": "list_repositories",
"params": {
"perPage": 5
}
}' \
https://your-worker-url.workers.dev
```
### 3. Test Write Operation
```bash
curl -X POST \
-H "Authorization: Bearer <your-github-token>" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": "test-3",
"method": "create_branch",
"params": {
"owner": "your-username",
"repo": "test-repo",
"branch": "test-branch"
}
}' \
https://your-worker-url.workers.dev
```
## Configuration Options
### Environment Variables
Configure these in `wrangler.toml` under `[vars]`:
| Variable | Default | Description |
|----------|---------|-------------|
| ENVIRONMENT | production | Environment name |
| LOG_LEVEL | info | Logging level (debug, info, warn, error) |
| MAX_BATCH_SIZE | 100 | Maximum files per batch operation |
| RATE_LIMIT_WINDOW | 60 | Rate limit window in seconds |
| RATE_LIMIT_MAX_REQUESTS | 100 | Maximum requests per window |
### Secrets
Configure these via `wrangler secret put`:
| Secret | Required | Description |
|---------|-----------|-------------|
| GITHUB_TOKEN | Yes | GitHub Personal Access Token |
| GITHUB_WEBHOOK_SECRET | No | Webhook secret for GitHub Actions |
| JWT_SECRET | Yes | Secret for JWT token signing (min 32 chars) |
| ENCRYPTION_KEY | Yes | Key for encrypting sensitive data (min 32 chars) |
### Custom Domains
Add a custom domain in `wrangler.toml`:
```toml
[env.production]
routes = [
{ pattern = "mcp.yourdomain.com/*", zone_name = "yourdomain.com" }
]
```
Or via Cloudflare Dashboard:
1. Go to Workers & Pages
2. Select your worker
3. Settings → Triggers
4. Add Custom Domain
## Monitoring
### Cloudflare Analytics
Access analytics via Cloudflare Dashboard:
1. Go to Workers & Pages
2. Select your worker
3. View Analytics → Metrics
Key metrics to monitor:
- Request count
- Error rate
- Response time
- Edge latency
- KV operations
### Audit Logs
Access audit logs via worker logs:
```bash
wrangler tail
```
Or via Cloudflare Dashboard:
1. Workers & Pages → Your Worker
2. Logs
### Health Monitoring
Set up external health monitoring:
```bash
# Simple health check script
#!/bin/bash
HEALTH_URL="https://your-worker-url.workers.dev/health"
response=$(curl -s -o /dev/null -w "%{http_code}" $HEALTH_URL)
if [ $response -eq 200 ]; then
echo "Health check passed"
exit 0
else
echo "Health check failed: HTTP $response"
exit 1
fi
```
## Rollback
### Rollback Deployment
Rollback to previous deployment:
```bash
# View deployment history
wrangler deployments list
# Rollback to specific deployment
wrangler rollback [deployment-id]
```
### Rollback GitHub Operations
Use the rollback handler to revert GitHub changes:
```bash
curl -X POST \
-H "Authorization: Bearer <your-token>" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": "rollback-1",
"method": "rollback_commit",
"params": {
"owner": "your-username",
"repo": "your-repo",
"branch": "main",
"targetSha": "previous-commit-sha"
}
}' \
https://your-worker-url.workers.dev
```
## Troubleshooting
### Common Issues
**Worker fails to start**
- Check `wrangler.toml` configuration
- Verify KV namespace IDs
- Ensure all secrets are set
**Authentication errors**
- Verify GitHub token is valid
- Check token has required permissions
- Confirm token hasn't expired
**Rate limit errors**
- Review rate limit configuration
- Check KV namespace is properly configured
- Monitor request patterns
**Deployment fails**
- Check Cloudflare account status
- Verify wrangler is logged in
- Review deployment logs: `wrangler tail`
**GitHub Actions not triggering**
- Verify webhook secret matches
- Check workflow file syntax
- Confirm worker URL is accessible
### Debug Mode
Enable debug logging:
```toml
[vars]
LOG_LEVEL = "debug"
```
Redeploy and check logs:
```bash
wrangler tail
```
## Cost Considerations
### Cloudflare Workers Pricing
- **Free Tier**: 100,000 requests/day
- **Paid Tier**: $5/month for 10 million requests
- **KV Storage**: $0.50/GB/month
- **KV Reads**: $0.50 per million reads
- **KV Writes**: $0.50 per million writes
### Optimization Tips
1. **Caching**: Enable response caching where appropriate
2. **Batching**: Use batch operations for multiple files
3. **Rate Limiting**: Configure appropriate rate limits
4. **Monitoring**: Regular review of usage metrics
## Security Best Practices
### 1. Secret Management
- Never commit secrets to repository
- Rotate secrets regularly (monthly recommended)
- Use different secrets for different environments
- Store secrets securely in Cloudflare
### 2. Token Permissions
- Use principle of least privilege
- Create separate tokens for staging/production
- Revoke tokens immediately after compromise
- Regular audit of token usage
### 3. Access Control
- Implement IP whitelisting if needed
- Use Cloudflare Access for additional protection
- Enable audit logging for compliance
- Regular review of audit logs
### 4. Network Security
- Enable HTTPS only (default with Workers)
- Configure WAF rules if needed
- Monitor for suspicious activity
- Set up alerting for anomalies
## Maintenance
### Regular Tasks
**Daily**
- Monitor error rates and response times
- Review audit logs for anomalies
**Weekly**
- Review usage metrics
- Check for new vulnerabilities in dependencies
- Verify rate limiting is working correctly
**Monthly**
- Rotate secrets
- Review and update policies
- Clean up old audit logs
- Review and update dependencies
### Updates
Update dependencies:
```bash
npm update
npm audit fix
```
Redeploy after updates:
```bash
wrangler deploy
```
## Support
For issues and questions:
- **GitHub Issues**: [repository-url]/issues
- **Documentation**: [docs/](docs/)
- **Cloudflare Workers Docs**: https://developers.cloudflare.com/workers/
- **Wrangler CLI**: https://developers.cloudflare.com/workers/wrangler/
## Additional Resources
- [MCP Specification](https://modelcontextprotocol.io/)
- [GitHub API Documentation](https://docs.github.com/en/rest)
- [Cloudflare Workers Documentation](https://developers.cloudflare.com/workers/)
- [Wrangler CLI Documentation](https://developers.cloudflare.com/workers/wrangler/)
