GitHub Webhook Setup Skill

Configure GitHub webhooks for automatic deployment on push events.

Quick Start

To add a new repo for auto-deployment:

1. Provide the repository name (e.g., "my-project")
2. Confirm the local project path exists on the server
3. Follow the GitHub webhook configuration steps

Example: "Set up webhook for my-project repo"

Table of Contents

1. When to Use This Skill
2. What This Skill Does
3. Instructions
   • 3.1 Verify WEBHOOK_SECRET
   • 3.2 Check Endpoint Accessibility
   • 3.3 Add Hook Configuration
   • 3.4 Guide GitHub Setup
   • 3.5 Test the Webhook
   • 3.6 Verify Deployment
4. Supporting Files
5. Expected Outcomes
6. Requirements
7. Red Flags to Avoid

When to Use This Skill

Explicit Triggers:

• "Set up webhook for [repo]"
• "Add GitHub auto-deploy for [repo]"
• "Configure webhook for [repository]"
• "New repo needs auto-deployment"

Implicit Triggers:

• Creating a new project that needs CI/CD
• Setting up a new service in the infrastructure
• Migrating a project to this server

Debugging Triggers:

• "Webhook not triggering"
• "Push event not deploying"
• "GitHub webhook returning 403/401"
• "Deployment not working"

What This Skill Does

1. Verifies Environment - Checks WEBHOOK_SECRET exists (generates if needed)
2. Tests Accessibility - Confirms webhook.temet.ai endpoint responds
3. Configures Hook - Adds entry to hooks.json for the new repo
4. Guides GitHub Setup - Provides exact steps for GitHub webhook configuration
5. Tests Integration - Validates webhook receives events correctly
6. Verifies Deployment - Confirms push triggers deployment script

Instructions

3.1 Verify WEBHOOK_SECRET

Check if WEBHOOK_SECRET exists in .env:

grep -E "^WEBHOOK_SECRET=" /home/dawiddutoit/projects/network/.env

If missing or placeholder value, generate a new secret:

openssl rand -hex 32

Add to .env:

WEBHOOK_SECRET=<generated-hex-string>

Important: After updating .env, restart the webhook container:

cd /home/dawiddutoit/projects/network && docker compose restart webhook

3.2 Check Endpoint Accessibility

Test the webhook health endpoint:

curl -I https://webhook.temet.ai/hooks/health

Expected response:

HTTP/2 200
content-type: text/plain; charset=utf-8

If not accessible:

1. Check Cloudflare tunnel is running: docker ps | grep cloudflared
2. Verify bypass policy exists for webhook.temet.ai
3. Check webhook container: docker ps | grep webhook
4. View webhook logs: docker logs webhook --tail 50

3.3 Add Hook Configuration

Location: /home/dawiddutoit/projects/network/config/hooks.json

Template for new hook:

{
  "id": "<repo-name>",
  "execute-command": "/scripts/deploy.sh",
  "command-working-directory": "/projects/<repo-name>",
  "pass-arguments-to-command": [
    {
      "source": "payload",
      "name": "repository.full_name"
    }
  ],
  "trigger-rule": {
    "and": [
      {
        "match": {
          "type": "payload-hmac-sha256",
          "secret": "WEBHOOK_SECRET",
          "parameter": {
            "source": "header",
            "name": "X-Hub-Signature-256"
          }
        }
      },
      {
        "match": {
          "type": "value",
          "value": "refs/heads/main",
          "parameter": {
            "source": "payload",
            "name": "ref"
          }
        }
      }
    ]
  },
  "response-message": "Deployment triggered for <repo-name>"
}

Key Fields:

Steps to add:

1. Read current hooks.json
2. Add new entry to the array (before closing ])
3. Restart webhook container: docker compose restart webhook

3.4 Guide GitHub Setup

Provide these exact instructions to the user:

GITHUB WEBHOOK CONFIGURATION

1. Go to your repository on GitHub
2. Click: Settings -> Webhooks -> Add webhook

3. Configure the webhook:
   - Payload URL: https://webhook.temet.ai/hooks/<repo-name>
   - Content type: application/json
   - Secret: <value-from-WEBHOOK_SECRET-in-.env>
   - SSL verification: Enable SSL verification (checked)

4. Events:
   - Select: "Just the push event"

5. Active: Checked

6. Click "Add webhook"

Important: The secret in GitHub MUST match WEBHOOK_SECRET in .env exactly.

3.5 Test the Webhook

Option A: Push to trigger

# Make a small change and push to main branch
git commit --allow-empty -m "Test webhook"
git push origin main

Option B: GitHub UI test

1. Go to repo Settings -> Webhooks
2. Click on the webhook
3. Go to "Recent Deliveries" tab
4. Click "Redeliver" on any delivery (or wait for a push)

Check webhook received the event:

docker logs webhook --tail 20

Expected log output:

[webhook] incoming HTTP request from X.X.X.X POST /hooks/<repo-name>
[webhook] <repo-name> got matched
[webhook] executing /scripts/deploy.sh

3.6 Verify Deployment

Check deployment script executed:

# View deploy logs
ls -la /tmp/deploy-*.log | tail -5

# Read latest deploy log
cat $(ls -t /tmp/deploy-*.log | head -1)

Expected log content:

[timestamp] === Deployment triggered for: owner/repo-name ===
[timestamp] Working directory: /projects/<repo-name>
[timestamp] Pulling latest changes...
[timestamp] Services updated successfully
[timestamp] === Deployment complete ===

Verify git pulled latest:

cd /projects/<repo-name> && git log -1 --oneline

Supporting Files

Expected Outcomes

Success:

• WEBHOOK_SECRET configured in .env
• hooks.json updated with new entry
• webhook.temet.ai/hooks/<repo-name> accessible
• GitHub webhook created and delivering
• Push events trigger deployment script
• Latest code pulled to server

Partial Success:

• Hook configured but GitHub not yet set up (user action needed)
• Webhook receiving but deployment script failing (check logs)

Failure Indicators:

• 401/403 from webhook endpoint -> Secret mismatch
• 404 from webhook endpoint -> Hook ID not in hooks.json
• "signature does not match" in logs -> Secret mismatch
• Deployment not running -> Check container logs

Requirements

Environment:

• Docker running with webhook container
• Cloudflare tunnel connected
• webhook.temet.ai with bypass authentication
• WEBHOOK_SECRET in .env

Server Setup:

• Repository cloned to /projects/<repo-name>
• Git configured for pull operations
• Docker compose available (if repo has docker-compose.yml)

GitHub:

• Repository admin access (to create webhooks)
• Main branch exists

Red Flags to Avoid

• Do not commit WEBHOOK_SECRET to git
• Do not use different secrets for different repos (one secret for all)
• Do not forget to restart webhook container after hooks.json changes
• Do not skip the health endpoint check
• Do not use HTTP (always HTTPS via tunnel)
• Do not add hooks for branches other than main without updating trigger-rule
• Do not skip testing with an actual push event
• Do not forget to clone the repo to /projects/ on the server first

Notes

• The webhook container reads WEBHOOK_SECRET as environment variable, referenced in hooks.json as "WEBHOOK_SECRET" (not the actual value)
• All repos share the same WEBHOOK_SECRET for simplicity
• The deploy.sh script is generic and works for any repo with docker-compose.yml
• Webhook endpoint has Cloudflare Access bypass (public access for GitHub)
• Deploy logs are written to /tmp/ with timestamps
• The health endpoint (/hooks/health) is useful for monitoring