agent-manager/README.md

Gogs Webhook Server

A modular Node.js server for receiving and processing Gogs webhooks. The server logs all incoming webhooks to the console and provides an extensible callback system for custom event handling.

Features

• Modular Architecture: Clean separation of concerns (server, handler, logger)
• Extensible Callback System: Register callbacks for specific events or all events
• Console Logging: Colored, formatted logging of all webhook events
• Health Check Endpoint: Built-in health monitoring
• Graceful Shutdown: Proper cleanup on process termination
• Zero Dependencies: Pure Node.js implementation

Requirements

• Node.js >= 18.0.0

Installation

npm install

Usage

Basic Usage (Logging Only)

Start the server with default configuration:

npm start

The server will start on port 3000 and log all incoming webhooks to the console.

Development Mode (Auto-reload)

npm run dev

Configuration

Configure the server using environment variables:

PORT=8080 WEBHOOK_PATH=/gogs WEBHOOK_SECRET=your-secret npm start

Available environment variables:

• PORT: Server port (default: 3000)
• WEBHOOK_PATH: Webhook endpoint path (default: /webhook)
• WEBHOOK_SECRET: Optional webhook secret for signature verification

Endpoints

• POST /webhook - Webhook endpoint
• GET /health - Health check endpoint

Extending with Callbacks

The server is designed to be easily extended with custom callbacks. See examples/with-callbacks.js for a complete example.

Register Event-Specific Callbacks

import { WebhookServer } from './src/server.js';

const server = new WebhookServer({ port: 3000 });
const handler = server.getHandler();

// Handle push events
handler.on('push', async (payload, headers) => {
  console.log('Push to:', payload.repository.name);
  console.log('Commits:', payload.commits.length);
  // Your custom logic here
});

// Handle pull request events
handler.on('pull_request', async (payload, headers) => {
  console.log('PR:', payload.action);
  // Your custom logic here
});

server.start();

Register Global Callbacks

// Handle all events
handler.onAny(async (eventType, payload, headers) => {
  console.log('Received event:', eventType);
  // Send to analytics, external logging, etc.
});

Run the Example

node examples/with-callbacks.js

Gogs Webhook Configuration

1. Go to your Gogs repository settings
2. Navigate to Webhooks → Add Webhook → Gogs
3. Configure:
   • Payload URL: http://your-server:3000/webhook
   • Content Type: application/json
   • Secret: (optional) your webhook secret
   • Events: Select which events to receive
4. Click "Add Webhook"

Supported Events

• push - Repository push
• create - Branch or tag creation
• delete - Branch or tag deletion
• pull_request - Pull request actions
• issues - Issue actions
• issue_comment - Issue comment actions
• release - Release actions

Project Structure

.
├── src/
│   ├── index.js           # Main entry point
│   ├── server.js          # HTTP server implementation
│   ├── webhookHandler.js  # Webhook processing and callbacks
│   └── logger.js          # Logging utility
├── examples/
│   └── with-callbacks.js  # Example with custom callbacks
├── package.json
└── README.md

Architecture

WebhookServer (src/server.js)

• Creates HTTP server
• Handles routing and request parsing
• Manages webhook verification
• Delegates webhook processing to handler

WebhookHandler (src/webhookHandler.js)

• Manages callback registration
• Executes callbacks for events
• Supports event-specific and global callbacks
• Provides error handling for callbacks

Logger (src/logger.js)

• Formats and colorizes console output
• Provides structured logging methods
• Handles timestamp formatting

Testing

You can test the webhook server using curl:

# Test health check
curl http://localhost:3000/health

# Test webhook with push event
curl -X POST http://localhost:3000/webhook \
  -H "Content-Type: application/json" \
  -H "X-Gogs-Event: push" \
  -H "X-Gogs-Delivery: 12345" \
  -d '{
    "ref": "refs/heads/main",
    "repository": {
      "name": "test-repo",
      "full_name": "user/test-repo"
    },
    "pusher": {
      "username": "testuser"
    },
    "commits": [
      {
        "id": "abc123",
        "message": "Test commit"
      }
    ]
  }'

License

ISC