mirror of
https://github.com/coleam00/Archon
synced 2026-04-21 21:47:53 +00:00
73cb4784a1
* refactor(core): break up god function in command-handler Extract handleWorktreeCommand, handleWorkflowCommand, handleRepoCommand, and handleRepoRemoveCommand from the 1300-line handleCommand switch statement. Add resolveRepoArg helper to eliminate duplication between repo and repo-remove cases. handleCommand now contains ~200 lines of routing logic only. * fix: address review findings from PR #742 command-handler.ts: - Replace fragile 'success' in discriminator with proper ResolveRepoArgResult discriminated union (ok: true/false) and fix misleading JSDoc - Add missing error handling to worktree orphans, workflow cancel, workflow reload - Fix isolation_env_id UUID used as filesystem path in worktree create/list/orphans (look up working_path from DB instead) - Add cmd. domain prefix to all log events per CLAUDE.md convention - Add identifier/isolationEnvId context to repo_switch_failed and worktree_remove_failed logs - Capture isCurrentCodebase before mutation in handleRepoRemoveCommand - Hoist duplicated workflowCwd computation in handleWorkflowCommand - Remove stale (Phase 3D) comment marker docs: - Remove all /command-invoke references from CLAUDE.md, README.md, docs/architecture.md, and .claude/rules/orchestrator.md - Update command list to match actual handleCommand cases - Replace outdated routing examples with current AI router pattern * refactor: remove MAX_WORKTREES_PER_CODEBASE limit Worktree count is no longer restricted. Remove the constant, the limit field from WorktreeStatusBreakdown, the limit_reached block reason, formatWorktreeLimitMessage, and all associated tests. * fix: address review findings — error handling, log prefixes, tests, docs - Wrap workflow list discoverWorkflowsWithConfig in try/catch (was the only unprotected async call among workflow subcommands) - Cast error to Error before logging in workflow cancel/status catch blocks - Add cmd. domain prefix to all command-handler log events (12 events) - Update worktree create test to use UUID isolation_env_id with DB lookup - Add resolveRepoArg boundary tests (/repo 0, /repo N > count) - Add worktree cleanup subcommand tests (merged, stale, invalid type) - Add updateConversation assertion to repo-remove session test - Fix stale docs: architecture.md command handler section, .claude → .archon paths, remove /command-invoke from commands-reference, fix github.md example
140 lines
4 KiB
Markdown
140 lines
4 KiB
Markdown
# GitHub Webhooks Setup
|
|
|
|
Connect Archon to GitHub so you can interact with your AI coding assistant from issues and pull requests.
|
|
|
|
## Prerequisites
|
|
|
|
- Archon server running (see [Getting Started](../getting-started.md))
|
|
- GitHub repository with issues enabled
|
|
- `GITHUB_TOKEN` set in your environment (see [Getting Started](../getting-started.md))
|
|
- Public endpoint for webhooks (see ngrok setup below for local development)
|
|
|
|
## Step 1: Generate Webhook Secret
|
|
|
|
On Linux/Mac:
|
|
```bash
|
|
openssl rand -hex 32
|
|
```
|
|
|
|
On Windows (PowerShell):
|
|
```powershell
|
|
-join ((1..32) | ForEach-Object { '{0:x2}' -f (Get-Random -Maximum 256) })
|
|
```
|
|
|
|
Save this secret - you'll need it for steps 3 and 4.
|
|
|
|
## Step 2: Expose Local Server (Development Only)
|
|
|
|
### Using ngrok (Free Tier)
|
|
|
|
```bash
|
|
# Install ngrok: https://ngrok.com/download
|
|
# Or: choco install ngrok (Windows)
|
|
# Or: brew install ngrok (Mac)
|
|
|
|
# Start tunnel
|
|
ngrok http 3090
|
|
|
|
# Copy the HTTPS URL (e.g., https://abc123.ngrok-free.app)
|
|
# Free tier URLs change on restart
|
|
```
|
|
|
|
Keep this terminal open while testing.
|
|
|
|
### Using Cloudflare Tunnel (Persistent URLs)
|
|
|
|
```bash
|
|
# Install: https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/
|
|
cloudflared tunnel --url http://localhost:3090
|
|
|
|
# Get persistent URL from Cloudflare dashboard
|
|
```
|
|
|
|
Persistent URLs survive restarts.
|
|
|
|
**For production deployments**, use your deployed server URL (no tunnel needed).
|
|
|
|
## Step 3: Configure GitHub Webhook
|
|
|
|
Go to your repository settings:
|
|
- Navigate to: `https://github.com/owner/repo/settings/hooks`
|
|
- Click "Add webhook"
|
|
- **Note**: For multiple repositories, you'll need to add the webhook to each one individually
|
|
|
|
**Webhook Configuration:**
|
|
|
|
| Field | Value |
|
|
|-------|-------|
|
|
| **Payload URL** | Local: `https://abc123.ngrok-free.app/webhooks/github`<br>Production: `https://your-domain.com/webhooks/github` |
|
|
| **Content type** | `application/json` |
|
|
| **Secret** | Paste the secret from Step 1 |
|
|
| **SSL verification** | Enable SSL verification (recommended) |
|
|
| **Events** | Select "Let me select individual events":<br>- Issues<br>- Issue comments<br>- Pull requests |
|
|
|
|
Click "Add webhook" and verify it shows a green checkmark after delivery.
|
|
|
|
## Step 4: Set Environment Variables
|
|
|
|
```env
|
|
WEBHOOK_SECRET=your_secret_from_step_1
|
|
```
|
|
|
|
**Important**: The `WEBHOOK_SECRET` must match exactly what you entered in GitHub's webhook configuration.
|
|
|
|
## Step 5: Configure Streaming (Optional)
|
|
|
|
```env
|
|
GITHUB_STREAMING_MODE=batch # batch (default) | stream
|
|
```
|
|
|
|
For streaming mode details, see [Advanced Configuration](../configuration.md).
|
|
|
|
## Usage
|
|
|
|
Interact by @mentioning `@Archon` in issues or PRs:
|
|
|
|
```
|
|
@Archon can you analyze this bug?
|
|
@Archon prime the codebase
|
|
@Archon review this implementation
|
|
```
|
|
|
|
**First mention behavior:**
|
|
- Automatically clones the repository to `/.archon/workspaces/`
|
|
- Detects and loads commands from `.archon/commands/` if present
|
|
- Injects full issue/PR context for the AI assistant
|
|
|
|
**Subsequent mentions:**
|
|
- Resumes existing conversation
|
|
- Maintains full context across comments
|
|
|
|
## Adding Additional Repositories
|
|
|
|
Once your server is running, add more repos by creating a webhook with the same secret:
|
|
|
|
```bash
|
|
# Get your existing webhook secret
|
|
WEBHOOK_SECRET=$(grep WEBHOOK_SECRET .env | cut -d= -f2)
|
|
|
|
# Add webhook to new repo (replace OWNER/REPO)
|
|
gh api repos/OWNER/REPO/hooks --method POST \
|
|
-f "config[url]=https://YOUR_DOMAIN/webhooks/github" \
|
|
-f "config[content_type]=json" \
|
|
-f "config[secret]=$WEBHOOK_SECRET" \
|
|
-f "events[]=issues" \
|
|
-f "events[]=issue_comment" \
|
|
-f "events[]=pull_request" \
|
|
-f "events[]=pull_request_review_comment"
|
|
```
|
|
|
|
Or via GitHub UI: **Repo Settings > Webhooks > Add webhook**
|
|
- **Payload URL**: Your server URL + `/webhooks/github`
|
|
- **Content type**: `application/json`
|
|
- **Secret**: Same `WEBHOOK_SECRET` from your `.env`
|
|
- **Events**: Issues, Issue comments, Pull requests, Pull request review comments
|
|
|
|
**Important**: The webhook secret must be identical across all repos.
|
|
|
|
## Further Reading
|
|
|
|
- [Advanced Configuration](../configuration.md)
|