Webhook Setup

Webhook Setup

After hub2lab is running and publicly reachable, configure webhooks on GitHub and GitLab.

Making hub2lab Reachable

hub2lab must be accessible from GitHub and GitLab servers. Options:

• Public IP/DNS: Deploy on a VPS with a public IP and domain
• Tunnel: Use ngrok for testing: ngrok http 3000
• Tailscale/Funnel: Use Tailscale Funnel to expose a local server

GitHub

Step 1: Organization Settings

1. Navigate to your GitHub organization → Settings → Webhooks → Add webhook
2. If you're using a personal account (not an org): Repository → Settings → Webhooks

Step 2: Configure Webhook

Field	Value
Payload URL	https://your-server:3000/webhook/github
Content type	application/json
Secret	Same as GITHUB_WEBHOOK_SECRET in your .env
SSL verification	Enable if using HTTPS (recommended)

Step 3: Select Events

For full functionality, select Let me select individual events and enable:

• Pushes — sync commits
• Branch or tag creation — sync new branches/tags
• Branch or tag deletion — record deletion markers
• Repositories — auto-create GitLab projects when repos are created
• (Optional) Pull requests, Issues, etc. — not handled by hub2lab

Alternatively, select Send me everything and hub2lab will ignore unknown event types.

Step 4: Add Webhook

Click Add webhook. GitHub sends a test ping; hub2lab logs Unhandled GitHub event type: ping — this is normal.

Required GitHub Token Scopes

Scope	Purpose
repo	Full control of private repositories (push, create branches, etc.)
admin:org	Read org membership (optional, for org-level events)

GitLab

Step 1: Group Settings

1. Navigate to your GitLab group → Settings → Webhooks
2. If using a personal namespace: Project → Settings → Webhooks

Step 2: Configure Webhook

Field	Value
URL	https://your-server:3000/webhook/gitlab
Secret token	Same as GITLAB_WEBHOOK_SECRET in your .env
SSL verification	Enable if using HTTPS

Step 3: Select Triggers

• Push events — sync commits
• Tag push events — sync tag creation/deletion
• (Optional) Other events — not handled by hub2lab

Step 4: Add Webhook

Click Add webhook. GitLab sends a test ping. Check hub2lab logs for confirmation.

Required GitLab Token Scopes

Scope	Purpose
api	Full API access (create projects, branches, etc.)
write_repository	Push files to repositories

Verification

Check hub2lab Logs

After adding webhooks, make a test push to a synced repo. Look for:

2026-07-20 [INFO] Processing GitHub push { event: 'push', org: 'my-org', repo: 'my-repo' }
2026-07-20 [INFO] Mirror-pushed refs/heads/main to target

Check the Target Platform

Verify the commits, branches, or tags appeared on the other side.

Test Webhook Delivery

• GitHub: Go to your webhook settings → Recent Deliveries — check for 202 responses
• GitLab: Go to your webhook settings — check for successful deliveries

Troubleshooting Webhooks

401 Unauthorized

• Check GITHUB_WEBHOOK_SECRET / GITLAB_WEBHOOK_SECRET match between .env and webhook settings
• Verify the secret hasn't been changed
• Check hub2lab logs for signature/token verification failure messages

202 Accepted But Nothing Happens

• Check hub2lab logs for errors during event processing
• Verify tokens have the correct scopes
• Check mapping configuration
• Ensure the target repository/group exists (or hub2lab can create it)

Delivery Failures

• Ensure hub2lab is publicly reachable
• Check firewall rules on port 3000 (or custom PORT)
• If using HTTPS behind a reverse proxy, ensure the proxy forwards correctly
• Check GitHub/GitLab delivery logs for timeout or connection errors