GitLab Event Forwarder

An AWS Lambda function that receives GitLab webhook events and forwards them to an SNS topic with structured metadata for filtering. Validates webhook signatures and extracts minimal metadata (source, event type, project/group paths) as SNS message attributes, enabling downstream subscribers to filter events precisely.

The original GitLab JSON payload is forwarded unchanged as the SNS message body.

Features

• Webhook Signature Validation: Verifies authenticity using GitLab’s X-Gitlab-Token header
• Structured Metadata: Extracts event type, project/group paths as SNS message attributes
• SNS Subscription Filtering: Enables precise event routing to subscribers
• Custom Domain: Optional custom domain with automatic TLS certificate management via ACM and Route53

Architecture

Single Lambda function handles the webhook processing:

1. Handler - API Gateway endpoint (/webhook) that validates GitLab webhook signatures, extracts metadata, and publishes to SNS

Prerequisites

• AWS CLI configured with appropriate credentials (IAM permissions for Lambda, API Gateway, SNS, CloudFormation, CloudWatch Logs, and optionally Route53/ACM for custom domain)
• Podman or Docker (for containerized SAM build/deploy)
• Python 3.11 or later (for development)

Deployment

Build and deploy using containerized AWS SAM CLI:

cd gitlab-event-forwarder
make build     # Build Lambda package
make deploy    # First deployment (interactive/guided)
make redeploy  # Subsequent deployments (non-interactive)

Deployment outputs: ApiEndpoint - API Gateway endpoint URL (<api-endpoint>)

Custom Domain

Optional custom domain with automatic TLS certificate management (ACM + Route53). Requires a Route53 hosted zone. Deploy with CustomDomainName and HostedZoneId parameters - CloudFormation handles certificate creation, DNS validation, and configuration. Certificate validation takes 5-30 minutes; allow up to 1 hour for DNS propagation.

Parameters

Resource naming: Lambda and API resources follow {ResourcePrefix}-{type}-{name} pattern (e.g., myapp-prod-lambda-handler, myapp-prod-api).

Prerequisites: Requires an existing SNS topic. Deploy hummingbird-events-topic first to create the topic, then use its ARN for the SnsTopicArn parameter.

Usage

Configure GitLab projects or groups to send webhooks to <api-endpoint>:

webhooks:
  <api-endpoint>:
    token: <secret-token>
    push_events: true
    merge_requests_events: true
    pipeline_events: true

SNS Subscription Filter Examples:

Push events from a specific project:

{
  "source": ["gitlab"],
  "event_type": ["push"],
  "project_path": ["redhat/hummingbird/containers"]
}

All merge request events:

{
  "source": ["gitlab"],
  "event_type": ["merge_request"]
}

Member events from a group:

{
  "source": ["gitlab"],
  "event_type": ["member"],
  "group_path": ["redhat/hummingbird"]
}

Development

See the main README for development workflows.

make setup     # Install dependencies
make check     # Lint code (ruff)
make fmt       # Format code
make test      # Run unit tests
make coverage  # Run tests with coverage

Configuration

Lambda function receives configuration via environment variables (automatically set by CloudFormation):

Event Metadata

The Lambda function extracts minimal metadata from GitLab webhook events and adds them as SNS message attributes:

Security & Limitations

Security:

• Webhook token validation using X-Gitlab-Token header
• Supports multiple active tokens for zero-downtime rotation
• Invalid/missing tokens return HTTP 401
• SNS topic follows least privilege principle
• CloudWatch logs capture all webhook deliveries (7-day retention)
• Sentry integration for error tracking

Limitations:

• Lambda timeout: 30 seconds
• Lambda memory: 256 MB
• Webhook payload size: Up to 6 MB (API Gateway limit)

License

This project is licensed under the GNU General Public License v3.0 or later - see the LICENSE file for details.