Skip to content

GitHub Webhook Configuration Checklist

Quick checklist for configuring the GitHub webhook for cluster-gitops repository.

Prerequisites Check

  • ArgoCD is deployed and accessible at https://argocd.camarades.net
  • DNS record for argocd.camarades.net points to ingress LoadBalancer IP
  • You have admin access to https://github.com/camaradesuk/cluster-gitops

Step 1: Get/Set Webhook Secret

Run these commands in your terminal:

# Check if webhook secret already exists
kubectl get secret argocd-secret -n argocd -o jsonpath='{.data.webhook\.github\.secret}' | base64 -d
echo  # Add newline for readability

If empty or you want to generate a new one:

# Generate a random secret
WEBHOOK_SECRET=$(openssl rand -hex 20)
echo "Save this secret: $WEBHOOK_SECRET"

# Store it in ArgoCD
kubectl patch secret argocd-secret -n argocd \
  -p "{\"data\":{\"webhook.github.secret\":\"$(echo -n $WEBHOOK_SECRET | base64)\"}}"

Copy the secret value - you'll need it in the next step.

Step 2: Create GitHub Webhook

  1. Go to: https://github.com/camaradesuk/cluster-gitops/settings/hooks
  2. Click "Add webhook"
  3. Fill in the form:
Field Value
Payload URL https://argocd.camarades.net/api/webhook
Content type application/json ⚠️ CRITICAL
Secret Paste the webhook secret from Step 1
SSL verification ✅ Enable SSL verification
Which events? Just the push event
Active ✅ Active
  1. Click "Add webhook"

Step 3: Test the Webhook

Method A: Test Delivery in GitHub UI

  1. Go to: https://github.com/camaradesuk/cluster-gitops/settings/hooks
  2. Click on the webhook you just created
  3. Scroll to "Recent Deliveries"
  4. If there's a delivery, click "Redeliver"
  5. Check for 200 OK response

Method B: Make a Test Commit

cd /home/chris/workspace/syrf/cluster-gitops
echo "$(date): Webhook test" >> .webhook-test
git add .webhook-test
git commit -m "test: verify webhook configuration"
git push

Then check GitHub webhook deliveries for a 200 OK response.

Step 4: Verify in ArgoCD

# Watch ArgoCD server logs for webhook events
kubectl logs -n argocd deployment/argocd-server --tail=20 -f | grep webhook

Expected log output: 

level=info msg="Received push event repo: https://github.com/camaradesuk/cluster-gitops.git"

Completion Checklist

  • Webhook secret stored in ArgoCD
  • GitHub webhook created with correct configuration
  • Content type set to application/json (not form-encoded)
  • Test delivery shows 200 OK response
  • ArgoCD logs show webhook events
  • Test commit triggers immediate sync (no 3-minute delay)

Troubleshooting

If webhook shows 403 Forbidden: 

# Verify secret matches
kubectl get secret argocd-secret -n argocd -o jsonpath='{.data.webhook\.github\.secret}' | base64 -d
echo
Compare with the secret entered in GitHub webhook settings.

If webhook shows Connection timeout: 

# Check ArgoCD ingress is accessible
curl -I https://argocd.camarades.net

# Check ingress is running
kubectl get ingress -n argocd
kubectl get pods -n ingress-nginx

If webhook shows 404 Not Found: - Verify URL is exactly: https://argocd.camarades.net/api/webhook (no typos) - Check ArgoCD server is running: kubectl get pods -n argocd | grep server

Optional: Configure Additional Repositories

Repeat Step 2 for other repositories ArgoCD watches:

  • camaradesuk/syrf (for Helm charts in monorepo)
  • Any other repos referenced by Applications/ApplicationSets

Use the same webhook secret for all repositories.

Cleanup (if testing)

Remove the test file created in Step 3:

cd /home/chris/workspace/syrf/cluster-gitops
git rm .webhook-test
git commit -m "chore: remove webhook test file"
git push