diff options
Diffstat (limited to 'archived/projt-launcher/docs/handbook/bot.md')
| -rw-r--r-- | archived/projt-launcher/docs/handbook/bot.md | 198 |
1 files changed, 198 insertions, 0 deletions
diff --git a/archived/projt-launcher/docs/handbook/bot.md b/archived/projt-launcher/docs/handbook/bot.md new file mode 100644 index 0000000000..807f1da838 --- /dev/null +++ b/archived/projt-launcher/docs/handbook/bot.md @@ -0,0 +1,198 @@ +# Bot `bot/` + +> **Type**: Cloudflare Worker +> **Platform**: Cloudflare Workers +> **Purpose**: PR Automation & Labeling +> **Latest Version**: 0.0.5-1 + +--- + +## Overview + +The ProjT Launcher bot is a Cloudflare Worker that automates pull request labeling based on changed files. It listens for GitHub webhook events and applies appropriate labels automatically. + +--- + +## Features + +| Feature | Description | +|---------|-------------| +| **Auto-labeling** | Labels PRs based on file changes | +| **Path mapping** | Configurable path-to-label rules | +| **Webhook integration** | GitHub webhook receiver | +| **Zero cold start** | Cloudflare Workers edge deployment | + +--- + +## Architecture + +``` +┌─────────────┐ ┌──────────────────┐ ┌─────────────┐ +│ GitHub │────▶│ Cloudflare │────▶ │ GitHub │ +│ Webhook │ │ Worker (bot/) │ │ API │ +└─────────────┘ └──────────────────┘ └─────────────┘ + │ + ┌──────▼────────┐ + │ wrangler.json │ + │ (config) │ + └───────────────┘ +``` + +--- + +## File Structure + +``` +bot/ +├── index.js # Main worker logic +├── server.js # Local development server +├── package.json # Dependencies +└── wrangler.json # Cloudflare configuration +``` + +--- + +## Label Rules + +The bot applies labels based on changed file paths: + +| Path Pattern | Label | +|--------------|-------| +| `launcher/**` | `launcher` | +| `buildconfig/**` | `build` | +| `cmake/**` | `build` | +| `.github/workflows/**` | `ci` | +| `docs/**` | `documentation` | +| `zlib/**` | `library: zlib` | +| `bzip2/**` | `library: bzip2` | +| `quazip/**` | `library: quazip` | +| `cmark/**` | `library: cmark` | +| `tomlplusplus/**` | `library: toml++` | +| `libqrencode/**` | `library: qrencode` | +| `website/**` | `website` | + +--- + +## Configuration + +### wrangler.json + +```json +{ + "name": "projtlauncher-bot", + "main": "index.js", + "compatibility_date": "2024-01-01", + "vars": { + "GITHUB_APP_ID": "your-app-id" + } +} +``` + +### Environment Variables + +| Variable | Description | +|----------|-------------| +| `GITHUB_APP_ID` | GitHub App ID | +| `GITHUB_APP_PRIVATE_KEY` | GitHub App private key | +| `GITHUB_WEBHOOK_SECRET` | Webhook signature secret | + +--- + +## Development + +### Prerequisites + +- Node.js 18+ +- Wrangler CLI (`npm install -g wrangler`) +- Cloudflare account + +### Local Development + +```bash +cd bot +npm install + +# Start local dev server +npm run dev +# or +wrangler dev +``` + +### Testing Webhooks Locally + +Use [smee.io](https://smee.io/) or ngrok to forward webhooks: + +```bash +# Install smee client +npm install -g smee-client + +# Forward webhooks +smee -u https://smee.io/your-channel -t http://localhost:8787 +``` + +--- + +## Deployment + +### Deploy to Cloudflare + +```bash +cd bot +wrangler publish +``` + +### GitHub Webhook Setup + +1. Go to repository Settings → Webhooks +2. Add webhook: + - **Payload URL**: `https://your-worker.workers.dev/webhook` + - **Content type**: `application/json` + - **Secret**: Your `GITHUB_WEBHOOK_SECRET` + - **Events**: Pull requests + +--- + +## API Endpoints + +| Endpoint | Method | Description | +|----------|--------|-------------| +| `/` | GET | Health check | +| `/webhook` | POST | GitHub webhook receiver | + +--- + +## Security + +- ✅ **Signature verification** — HMAC-SHA256 webhook signatures +- ✅ **App authentication** — GitHub App JWT tokens +- ✅ **Secret management** — Cloudflare Workers secrets + +--- + +## Troubleshooting + +### Bot not labeling PRs + +1. Check Cloudflare Workers logs +2. Verify webhook delivery in GitHub settings +3. Ensure secrets are configured correctly + +### Labels not created + +Labels must exist in the repository before the bot can apply them. + +--- + +## Related Documentation + +- [CI Workflows](./workflows.md) — GitHub Actions integration +- [GitHub Scripts](./ptcigh.md) — Additional automation + +--- + +## External Links + +- [Cloudflare Workers Docs](https://developers.cloudflare.com/workers/) +- [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/) +- [GitHub Apps](https://docs.github.com/en/apps) +- [GitHub Webhooks](https://docs.github.com/en/webhooks) |