GitHub Webhooks

Set up GitHub webhooks to trigger Sluice pipelines.

GitHub Webhooks

This guide walks you through setting up GitHub webhooks to automatically trigger your Sluice pipelines.

Prerequisites

• A Sluice pipeline configured and ready
• Admin access to your GitHub repository
• Your pipeline’s webhook URL and secret

Step 1: Get Webhook Details

1. Navigate to your pipeline in Sluice
2. Go to Settings > Webhooks
3. Copy the Webhook URL
4. Copy the Webhook Secret

Step 2: Configure GitHub

1. Go to your GitHub repository
2. Click Settings > Webhooks
3. Click Add webhook

Fill in the form:

Step 3: Select Events

Choose which events trigger the webhook:

Recommended: Just the push event

For most CI/CD pipelines, select Just the push event.

Individual events

For more control, select Let me select individual events:

• Pushes - Trigger on code push
• Pull requests - Trigger on PR activity
• Releases - Trigger on release published
• Branch or tag creation - Trigger on new branch/tag

Step 4: Activate

1. Ensure Active is checked
2. Click Add webhook
3. GitHub will send a ping event to verify

Verify Setup

After adding the webhook:

1. Go to the webhook you just created
2. Click on the Recent Deliveries tab
3. Look for a successful ping delivery (green checkmark)

If the ping failed:

• Check the Response tab for error details
• Verify the webhook URL is correct
• Ensure the secret matches

Test with a Push

Make a test commit:

git commit --allow-empty -m "Test webhook"
git push

Then verify:

1. Check GitHub’s Recent Deliveries for a successful delivery
2. Check Sluice for a new pipeline run
3. Verify the run shows the correct commit info

Event Payloads

Push Event

When code is pushed, GitHub sends:

{
  "ref": "refs/heads/main",
  "before": "abc123...",
  "after": "def456...",
  "repository": {
    "full_name": "org/repo",
    "clone_url": "https://github.com/org/repo.git"
  },
  "pusher": {
    "name": "username",
    "email": "[email protected]"
  },
  "commits": [...]
}

Pull Request Event

When PR activity occurs:

{
	"action": "opened",
	"number": 42,
	"pull_request": {
		"title": "Add feature",
		"head": {
			"ref": "feature-branch",
			"sha": "abc123..."
		},
		"base": {
			"ref": "main"
		}
	}
}

Branch Protection

For protected branches, you might want to require status checks:

1. Go to Settings > Branches
2. Click Add rule or edit existing
3. Enable Require status checks to pass
4. Search for and select Sluice checks

Troubleshooting

Webhook not triggering

1. Check if the webhook is Active in GitHub settings
2. Verify Recent Deliveries shows the event
3. Check the response status and body

Signature validation failed

1. Regenerate the secret in Sluice
2. Update the secret in GitHub
3. Redeliver a recent event to test

Wrong branch triggering

Configure branch filters in your Sluice pipeline settings to control which branches trigger runs.

GitHub Enterprise

For GitHub Enterprise Server:

1. Use your enterprise instance URL for repository cloning
2. Configure firewall rules to allow outbound webhooks to Sluice
3. Ensure SSL certificates are valid

Next Steps

• Webhook Overview - General webhook concepts
• Pipeline Configuration - Configure your pipeline