Take GitHub Webhooks Event Processing to the Next Level

Introduction

GitHub Actions are an integral part of many CI/CD workflows. They are amazing and can automate many processes providing a consistent and repeatable experience for your DevOps teams. But GitHub Actions (GHAs) are not perfect and have limitations that may not align with your team’s needs. One such limitation is scaling actions across multiple repositories and GitHub organizations. Performing actions specific to an individual repo is common and can easily be handled with built-in or custom action runners. But when you have a desire to perform actions across many repositories or organizations there is another GitHub feature that should be considered.

The power of organization webhooks

Organization webhooks are extremely powerful and flexible. You can subscribe to many events and send event payloads to a specific URL to be processed. This allows for webhooks to be leveraged in many common situations, such as triggering external processes, sending notifications and integrating with third-party platforms to name just a few. The possibilities are endless, and we quickly realized leveraging webhooks was crucial to handling common activities across multiple GitHub organizations. To learn more about GitHub webhooks, see the official documentation located here.

Solution Overview

One of the key tenets of a DevOps mindset is the freedom to experiment and building a GitHub event processing framework, based on webhooks, was vital for our team. The framework described below was built on Amazon Web Services (AWS) and leverages the following services:

• Elastic Load Balancing
• AWS Lambda
• Amazon EventBridge

The basic model is a producer/consumer design with a consumer of the GitHub webhook event validating and processing the request and then publishing the event to an Amazon EventBridge event bus for consumption.

Figure 1. Producer Architecture

Figure 2. Consumer Architecture

It should be noted this is not the only solution we considered, but it did meet our needs the best. Depending on your requirements, AWS Lambda Public Endpoint or Amazon API Gateway could also be considered instead of an application load balancer to handle events.

Design considerations

Decoupling the webhook processor from the event handler was a key design choice to safeguard the external facing components from engineers developing custom event handlers. Further separation can be achieved by utilizing cross-account access with Amazon EventBridge notifications. You can read more about this concept here. The application load balancer’s security group only allows connections from GitHub’s address ranges, checks the request header to ensure the request matches our expectations, and then uses path-based routing to send the payload to the appropriate AWS Lambda-based validation handler. The validation handler then performs payload checksum validation to confirm the request legitimately came from our configured webhooks via a shared secret key. After validation is completed, the lambda then places the event onto the EventBridge event bus for consumers to use with their solutions.

This solution is both extensible and scalable, allowing thousands of repositories across multiple GitHub organizations to easily have common features and capabilities. The possibilities are endless, but here are some ideas:

• Automated notification mechanisms for GitHub releases, pull requests, issues and discussions.
• Activity response and automation, such as when a label is added to an issue.
• Integration with third-party systems and workflows.
• Automated code review and analysis of pull requests.
• Collecting contribution metrics across your teams.

Conclusion

If you have not given GitHub Organization webhooks a serious look then you may be missing an immensely powerful feature that will give your DevOps team the flexibility to create endless custom automations, taking your internal workflows to the next level. Creating an event processing framework like how this document outlined will enable your team to experiment safely and securely so they can focus on building impactful, cloud-native solutions