Skip to content

GitHub Integration & Auto-Deploy

Webhook-based automatic deployment from GitHub pushes.

Overview

When you push to a GitHub repository, a webhook automatically redeploys the service on collabrains.eu.

Webhook Receiver

Component Details
Location /data/webhook-receiver/
Port 5000 (internal)
URL https://collabrains.eu:5000/webhook/github
Status Running in Docker

GitHub Setup

1. Configure Webhook in GitHub

Repository → Settings → Webhooks → Add webhook

Settings: - Payload URL: https://collabrains.eu:5000/webhook/github - Content type: application/json - Secret: Store in /data/webhook-receiver/.env as GITHUB_SECRET - Events: Push events (or select specific branches)

2. Environment Variable

The webhook secret must match in /data/webhook-receiver/.env:

cat /data/webhook-receiver/.env | grep GITHUB_SECRET

How It Works

GitHub Push
    ↓
Webhook POST to https://collabrains.eu:5000/webhook/github
    ↓
webhook-receiver validates signature
    ↓
Triggers deployment script
    ↓
Service redeploys (docker pull + restart)

Testing Webhook

View Webhook Logs

docker logs webhook-receiver-webhook-1 --tail 20 -f

Test Webhook Delivery

GitHub provides webhook delivery logs: 1. Repository → Settings → Webhooks 2. Click webhook 3. View "Recent Deliveries"

Manual Test

# Test webhook endpoint
curl -I https://collabrains.eu:5000/webhook/github

# Test with payload (requires valid signature)
# Use GitHub's test delivery or:
curl -X POST https://collabrains.eu:5000/webhook/github \
  -H "Content-Type: application/json" \
  -d '{"action":"opened"}'

Configuration

Webhook Receiver .env

Location: /data/webhook-receiver/.env

Key variables:

GITHUB_SECRET=<your-webhook-secret>
PORT=5000
REPO_PATH=/data/services/

Troubleshooting

Webhook Not Triggering

  1. Check webhook receiver is running: bash docker ps | grep webhook

  2. Check logs: bash docker logs webhook-receiver-webhook-1 --tail 50

  3. Verify GitHub webhook delivery:

  4. Go to webhook settings
  5. Check "Recent Deliveries"
  6. Look for red X (failed) or green checkmark (success)

Webhook Signature Validation Fails

Symptoms: "403 Forbidden" or "Invalid signature"

Cause: Secret mismatch between GitHub and webhook-receiver

Fix: 1. Get GitHub webhook secret 2. Update /data/webhook-receiver/.env 3. Restart webhook-receiver: bash docker restart webhook-receiver-webhook-1

Service Not Redeploying

  1. Check webhook is triggering (see logs)
  2. Verify deployment script has correct path
  3. Check service docker-compose file location
  4. View deployment logs: bash docker logs webhook-receiver-webhook-1 -f

Multiple Repositories

To trigger deploys for multiple repos:

  1. Add same webhook to each GitHub repo
  2. Webhook receiver should distinguish by repo name
  3. Edit deployment script if needed: bash cat /data/webhook-receiver/deploy.sh

Security

⚠️ Important security considerations:

  1. Keep webhook secret secure
  2. Don't commit to git
  3. Store in /data/webhook-receiver/.env only

  4. Use strong random string

  5. HTTPS only

  6. Webhook URL must be HTTPS

  7. Let's Encrypt certificate manages this

  8. Validate signatures

  9. Webhook receiver validates GitHub signature

  10. Prevents unauthorized deployments

  11. Limited permissions

  12. Deployment script runs as docker user
  13. Restrict access to service files only

Webhook Flow Diagram

GitHub Repository
    │
    ├─ Developer pushes code
    │
    └─ Webhook event triggered
        ↓
    HTTPS POST to collabrains.eu:5000/webhook/github
        ↓
    Webhook receiver validates:
        ├─ HTTPS connection ✓
        ├─ Signature verification ✓
        └─ Payload format ✓
        ↓
    Extract repo info from payload
        ├─ Repo name
        ├─ Branch
        └─ Commit hash
        ↓
    Trigger deployment script
        ├─ cd to service directory
        ├─ git pull latest
        └─ docker compose up -d --build
        ↓
    Service redeploys
        ↓
    Webhook receiver logs result

Monitoring Deployments

Check Deployment History

# View webhook receiver logs
docker logs webhook-receiver-webhook-1 --tail 100

# Filter for deployment events
docker logs webhook-receiver-webhook-1 | grep -i "deploy\|success\|error"

GitHub Webhook Deliveries

Webhook delivery status is visible in GitHub: 1. Repository → Settings → Webhooks 2. Click the webhook URL 3. "Recent Deliveries" shows status and timestamp

Best Practices

  1. Use branch protection rules
  2. Require PR reviews before push

  3. Prevents accidental deploys

  4. Test locally first

  5. Don't rely on webhook for first test

  6. Verify code works before push

  7. Monitor deployments

  8. Check webhook logs regularly

  9. Set up alerts for failures

  10. Limit webhook scope

  11. Only trigger on specific branches

  12. Use specific events (push, release)

  13. Backup before deploy

  14. Automated daily backups already running
  15. Manual backup before major changes

Disabling Webhook

To pause auto-deploys:

# Stop webhook receiver temporarily
docker stop webhook-receiver-webhook-1

# Or remove webhook in GitHub:
# Repository → Settings → Webhooks → Delete