GitHub Pull Request Webhook Integration

Overview

This workflow processes GitHub pull request webhooks to automatically create and manage ephemeral environments. When a PR is opened, updated, or closed, the webhook triggers appropriate actions in the Blueberry IDP.

Prerequisites

• [ ] Access Requirements
• Admin access to GitHub repository settings
• Blueberry API webhook endpoint URL

• Webhook secret for signature validation

• [ ] Tools and Software

• GitHub repository with admin permissions
• openssl for generating webhook secrets

• curl for testing webhooks

• [ ] Knowledge Requirements

• Understanding of GitHub webhook events
• Familiarity with HMAC signature validation
• Basic knowledge of HTTP headers

Steps

1. Generate Webhook Secret

Create a secure webhook secret:

# Generate a random secret
openssl rand -hex 32

# Save it securely - you'll need it for both GitHub and Blueberry
export WEBHOOK_SECRET="your-generated-secret"

# Store in Google Secret Manager for Blueberry
gcloud secrets create github-webhook-secret \
  --data-file=- <<< "$WEBHOOK_SECRET"

2. Configure Blueberry to Accept Webhooks

Update the Blueberry configuration:

# In your Helm values or environment config
webhooks:
  github:
    enabled: true
    secret: github-webhook-secret  # Reference to Secret Manager
    allowedOrganizations:
      - "your-org"
    allowedRepositories:
      - "your-org/your-repo"

3. Create GitHub Webhook

In your GitHub repository settings:

1. Navigate to Settings → Webhooks → Add webhook
2. Configure the webhook:

Payload URL: https://blueberry.example.com/api/webhooks/github
Content type: application/json
Secret: [paste your generated secret]
SSL verification: Enable

Which events would you like to trigger this webhook?
☑ Pull requests
☐ Pushes
☐ Everything

1. Click Add webhook

4. Verify Webhook Configuration

Test the webhook delivery:

# In GitHub webhook settings, click "Recent Deliveries"
# Find the ping event and check the response

# Or send a test webhook manually
curl -X POST https://blueberry.example.com/api/webhooks/github \
  -H "Content-Type: application/json" \
  -H "X-GitHub-Event: ping" \
  -H "X-Hub-Signature-256: sha256=$(echo -n '{"zen":"test"}' | openssl dgst -sha256 -hmac $WEBHOOK_SECRET -binary | xxd -p)" \
  -d '{"zen":"test"}'

Expected Response:

{
  "status": "pong",
  "message": "Webhook configured successfully"
}

5. Configure Environment Creation Rules

Set up rules for when to create environments:

# In Blueberry webhook configuration
webhook_rules = {
    "create_on": ["opened", "synchronize"],
    "delete_on": ["closed", "merged"],
    "skip_draft": True,
    "required_labels": ["deploy-preview"],
    "branch_pattern": "^(feature|fix)/.*$"
}

Webhook Event Processing

Pull Request Opened

When a PR is opened, Blueberry:

1. Validates the webhook
   python # Signature validation signature = request.headers.get("X-Hub-Signature-256") if not validate_signature(signature, request.body, webhook_secret): return 401

2. Extracts PR information
   json { "action": "opened", "number": 123, "pull_request": { "head": { "ref": "feature/new-feature", "sha": "abc123" } } }

3. Creates environment
   bash # Equivalent API call curl -X POST https://blueberry.example.com/api/environments \ -d '{ "name": "pr-123", "pr_number": 123, "pr_branch": "feature/new-feature", "git_commit_sha": "abc123" }'

Pull Request Updated

When a PR is synchronized (new commits pushed):

1. Updates the existing environment
2. Triggers new deployment with latest commit
3. Posts status back to GitHub

Pull Request Closed

When a PR is closed or merged:

1. Deletes the associated environment
2. Cleans up all resources
3. Updates GitHub commit status

Validation

Verify the webhook integration is working:

1. Check Webhook Deliveries
2. In GitHub: Settings → Webhooks → Recent Deliveries

3. All should show green checkmarks

4. Monitor Blueberry Logs
   bash kubectl logs -n blueberry deployment/blueberry-api -f | grep webhook

5. Verify Environment Creation

6. Open a test PR with required labels
7. Check that environment is created within 2-3 minutes
8. Verify GitHub commit status is updated

Troubleshooting

Webhook Signature Validation Fails

Symptoms:
- 401 Unauthorized responses
- "Invalid signature" in logs

Cause:
Webhook secret mismatch

Solution:

# Verify secret in both places matches
# GitHub: Settings → Webhooks → Edit → Secret
# Blueberry: Check Secret Manager value

gcloud secrets versions access latest --secret=github-webhook-secret

Environment Not Created

Symptoms:
- Webhook delivers successfully
- No environment created
- No errors in logs

Cause:
PR doesn't meet creation criteria

Solution:
Check webhook rules:
- PR has required labels
- Branch name matches pattern
- PR is not a draft
- Repository is in allowed list

GitHub Status Not Updated

Symptoms:
- Environment created successfully
- No status appears on GitHub PR

Cause:
Missing GitHub API token or permissions

Solution:

# Verify GitHub token has required permissions
# repo:status - to post commit statuses

# Check token is configured
kubectl get secret -n blueberry github-token

Security Considerations

• Always validate webhook signatures
• Use HTTPS for webhook endpoints
• Rotate webhook secrets regularly
• Limit allowed organizations/repositories
• Log all webhook events for audit
• Rate limit webhook endpoints

Performance Impact

• Webhook Processing: < 100ms
• Environment Creation: 2-3 minutes
• Concurrent Webhooks: Up to 50/second
• Queue Depth: 1000 pending webhooks

Related Workflows

• GitLab Webhook Integration
• Create Environment
• ArgoCD Integration
• API Authentication

References

• GitHub Webhook Documentation
• Webhook Security Best Practices
• Blueberry Webhook API

Last Updated: 2024-01-15
Author: Platform Team
Review Status: Approved