blackroad-operating-system/docs/OPERATOR_SETUP_GUIDE.md

Operator Engine Setup Guide

Complete setup instructions for Phase Q2 PR automation

---

Prerequisites

• GitHub Personal Access Token with repo scope
• Webhook endpoint (Railway, Heroku, or custom server)
• PostgreSQL database (for queue persistence - optional)
• Redis (for caching - optional)

Step 1: Environment Variables

Add to your .env file or Railway/Heroku config:

# Required
GITHUB_TOKEN=ghp_your_github_personal_access_token_here
GITHUB_WEBHOOK_SECRET=your_random_secret_string_here

# Optional
OPERATOR_WEBHOOK_URL=https://your-domain.com/api/operator/webhooks/github
MAX_QUEUE_WORKERS=5
MAX_ACTIONS_PER_REPO=10
ACTION_RETRY_MAX=3

Generating GitHub Token

1. Go to GitHub Settings → Developer Settings → Personal Access Tokens
2. Click "Generate new token (classic)"
3. Select scopes:
   • repo (full control of private repositories)
   • workflow (update GitHub Actions workflows)
   • write:discussion (write discussions)
4. Copy token and save as GITHUB_TOKEN

Generating Webhook Secret

python -c "import secrets; print(secrets.token_urlsafe(32))"

Save output as GITHUB_WEBHOOK_SECRET

Step 2: Deploy Operator Engine

Option A: Railway (Recommended)

# Operator Engine is bundled with backend deployment
railway up

The Operator Engine router is automatically included in the FastAPI app.

Option B: Standalone Deployment

If deploying separately:

# Clone repo
git clone https://github.com/blackboxprogramming/BlackRoad-Operating-System
cd BlackRoad-Operating-System

# Install dependencies
pip install -r backend/requirements.txt

# Run backend (includes Operator Engine)
cd backend
uvicorn app.main:app --host 0.0.0.0 --port $PORT

Step 3: Configure GitHub Webhooks

For Single Repository

1. Go to repository Settings → Webhooks
2. Click Add webhook
3. Configure:
   • Payload URL: https://your-domain.com/api/operator/webhooks/github
   • Content type: application/json
   • Secret: Your GITHUB_WEBHOOK_SECRET
   • SSL verification: Enable
   • Events: Select individual events:
     • Pull requests
     • Pull request reviews
     • Pull request review comments
     • Issue comments
     • Check suites
     • Check runs
     • Workflow runs
4. Click Add webhook

For Organization (All Repos)

1. Go to organization Settings → Webhooks
2. Follow same steps as above
3. Webhook will apply to all repos in org

Verify Webhook

After adding, send a test payload:

1. Go to webhook settings
2. Click Recent Deliveries
3. Click Redeliver on any event
4. Check response is 200 OK

Step 4: Enable Merge Queue

Update Branch Protection Rules

1. Go to repository Settings → Branches
2. Find main branch protection rule (or create one)
3. Configure:
   • Require status checks to pass before merging
   • Require branches to be up to date before merging
   • Require pull request reviews (disabled for auto-merge)
   • Required status checks:
     • Backend Tests
     • CI / validate-html
     • CI / validate-javascript
4. Save changes

Create Merge Queue Config

The merge queue config is already in .github/merge_queue.yml.

GitHub will automatically detect this file and enable merge queue features (requires GitHub Enterprise or GitHub Team).

Step 5: Set Up Prism Console

Access the Dashboard

# Local development
open prism-console/pages/merge-dashboard.html

# Production
https://your-domain.com/prism-console/pages/merge-dashboard.html

Configure API Endpoint

Update prism-console/modules/merge-dashboard.js:

const apiBaseUrl = '/api/operator';  // Production
// const apiBaseUrl = 'http://localhost:8000/api/operator';  // Local

Step 6: Create GitHub Teams (For Auto-Merge)

Required Teams

Create these teams in your GitHub organization:

1. claude-auto - For Claude AI automated changes
2. atlas-auto - For Atlas AI automated changes
3. docs-auto - For documentation-only changes
4. test-auto - For test-only changes

Team Settings

For each team:

1. Go to organization Teams
2. Click New team
3. Name: claude-auto (or respective name)
4. Description: "Auto-merge for Claude AI changes"
5. Add team to .github/CODEOWNERS:

   /docs/ @alexa-amundson @blackboxprogramming/docs-auto
   

Step 7: Start the Queue

Automatic Start (Recommended)

The queue starts automatically when the FastAPI app boots:

# In backend/app/main.py

@app.on_event("startup")
async def startup():
    from operator_engine.pr_actions import get_queue
    queue = get_queue()
    await queue.start()
    logger.info("Operator Engine queue started")

Manual Start

If needed, start manually:

from operator_engine.pr_actions import get_queue

queue = get_queue()
await queue.start()

Verify Queue is Running

curl https://your-domain.com/api/operator/health

Expected response:

{
  "status": "healthy",
  "queue_running": true,
  "queued": 0,
  "processing": 0,
  "completed": 5,
  "failed": 0,
  "workers": 5
}

Step 8: Test the System

Create a Test PR

1. Create a branch: git checkout -b claude/test-automation
2. Make a simple change (e.g., update README)
3. Commit: git commit -m "docs: test automation"
4. Push: git push -u origin claude/test-automation
5. Open PR on GitHub

Verify Automation

Check that:

1. PR is auto-labeled (should have docs label)
2. PR is added to merge queue (check Prism Console)
3. Checks run automatically
4. PR merges automatically after checks pass

Check Logs

# View Operator Engine logs
railway logs --service backend | grep "operator_engine"

# Or locally
tail -f logs/operator.log

Step 9: Monitor and Tune

Key Metrics to Watch

• Queue depth - Keep < 10 for optimal performance
• Merge velocity - Target 15-20 merges/hour
• Failure rate - Keep < 10%
• Time in queue - Target < 15 minutes

Tuning Parameters

If queue is slow:

# .github/merge_queue.yml
queue:
  batch_size: 3  # Reduce for faster processing
  check_timeout: 20  # Reduce if checks are fast

If too many failures:

auto_merge:
  require_reviews: true  # Enable reviews for quality
  excluded_patterns:  # Add more exclusions
    - "critical_file.py"

Troubleshooting

Webhooks Not Being Received

Check:

# Test webhook endpoint
curl -X POST https://your-domain.com/api/operator/webhooks/github \
  -H "Content-Type: application/json" \
  -H "X-GitHub-Event: ping" \
  -d '{"zen": "test"}'

Solutions:

• Verify endpoint is publicly accessible
• Check firewall rules
• Verify SSL certificate is valid
• Check webhook secret matches

Queue Not Processing Actions

Check:

curl https://your-domain.com/api/operator/queue/stats

Solutions:

• Restart the queue: await queue.stop(); await queue.start()
• Check worker count: Increase MAX_QUEUE_WORKERS
• Review error logs
• Verify GITHUB_TOKEN has correct permissions

Actions Failing

Check:

curl https://your-domain.com/api/operator/queue/action/{action_id}

Common Issues:

1. 403 Forbidden - GitHub token lacks permissions
2. 404 Not Found - PR or comment doesn't exist
3. 422 Unprocessable - Invalid parameters
4. 429 Rate Limited - Slow down requests

Auto-Merge Not Working

Checklist:

• PR has auto-merge label (claude-auto, docs, etc.)
• All required checks are passing
• Branch is up-to-date with base
• No merge conflicts
• Branch protection rules allow auto-merge
• PR is not in draft mode

Advanced Configuration

Custom Action Handlers

Add custom handlers for your workflow:

# operator_engine/pr_actions/handlers/custom_handler.py

from . import BaseHandler
from ..action_types import PRAction

class CustomHandler(BaseHandler):
    async def execute(self, action: PRAction):
        # Your custom logic
        return {"status": "success"}

# Register in handlers/__init__.py
from .custom_handler import CustomHandler

HANDLER_REGISTRY[PRActionType.CUSTOM_ACTION] = CustomHandler()

Database Persistence (Optional)

Store queue state in PostgreSQL:

# operator_engine/pr_actions/persistence.py

from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker

engine = create_engine(os.getenv("DATABASE_URL"))
Session = sessionmaker(bind=engine)

class PersistentQueue(PRActionQueue):
    async def enqueue(self, action):
        # Save to database
        session = Session()
        session.add(action)
        session.commit()
        return await super().enqueue(action)

Slack Notifications

Add Slack webhook for notifications:

# operator_engine/notifications.py

import httpx

async def notify_slack(message: str):
    webhook_url = os.getenv("SLACK_WEBHOOK_URL")
    if not webhook_url:
        return

    async with httpx.AsyncClient() as client:
        await client.post(webhook_url, json={"text": message})

# Use in handlers
await notify_slack(f"PR #{pr_number} merged successfully! 🎉")

Maintenance

Weekly Tasks

• Review failed actions in Prism Console
• Check queue depth trends
• Update GITHUB_TOKEN if expiring
• Review and adjust priority rules

Monthly Tasks

• Audit merge queue metrics
• Review and update auto-merge labels
• Clean up old action logs
• Update documentation

Quarterly Tasks

• Review security settings
• Update dependencies
• Optimize slow handlers
• Plan new automation features

---

Status: ✅ Production Ready (Phase Q2) Maintainer: @alexa-amundson Last Updated: 2025-11-18