README.md

Buildkite PubSub Webhook

A webhook handler that securely forwards Buildkite build events to Google Cloud Pub/Sub, enabling event-driven architectures and integrations with your Buildkite pipelines.

Overview

This service connects Buildkite's webhook system to Google Cloud Pub/Sub, allowing you to:

• Receive Buildkite build events (status changes, pipeline updates, etc.)
• Forward events securely to Pub/Sub topics
• Monitor and alert on webhook delivery
• Filter and process events using Pub/Sub subscriptions
• Build event-driven workflows and integrations

Prerequisites

• Go 1.20+ for development
• Docker for container builds
• kubectl for deployment
• Orbstack for local Kubernetes
• ngrok for local webhook testing
• Google Cloud Project with Pub/Sub enabled
• Buildkite organization admin access for webhook configuration

Documentation

1. Getting Started

   • Quick Start Guide - Complete deployment walkthrough
   • Google Cloud Setup - Service account and permissions setup

2. Usage & Integration

   • Usage Guide - Event patterns and examples
   • Event Schema - Event payloads and attributes
   • Monitoring - Metrics, alerts, and debugging
   • Event Filtering - Pub/Sub subscription examples

Features

• 🔄 Event Handling

  • Standardized event transformation
  • Support for all Buildkite event types
  • Configurable event filtering
  • Reliable delivery with retries

• 🔒 Security

  • Webhook token validation
  • Rate limiting (global and per-IP)
  • TLS termination
  • Security headers

• 📊 Observability

  • Prometheus metrics
  • Grafana dashboards
  • Health checks
  • Alert templates

• 🚀 Deployment

  • Kubernetes manifests
  • Horizontal scaling
  • Resource management
  • Zero-downtime updates

Local Development

# Run locally
go run cmd/webhook/main.go

# Run tests
go test ./...

# Build container
docker build -t buildkite-webhook .

Deployment

Follow the Quick Start Guide for complete deployment instructions, or see individual guides:

• GCP Setup Guide for Google Cloud configuration
• Usage Guide for event handling patterns

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -am 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see LICENSE file for details.