Configuring Real-Time Event Handlers

In this guide, you will:

Set up Event Handlers in the Guardrails workspace using the Guardrails console.
Monitor and troubleshoot the Event Handlers setup process.

Guardrails enables organizations to selectively install policies, controls, and guardrails tailored to specific services. The Event Handler simplifies cloud management by providing a unified framework for responding to and managing events, ensuring proactive governance and security across cloud environments. Event Handlers for GitHub are responsible for conveying events from GitHub back to Guardrails for processing.

Prerequisites

Turbot/Operator permissions at the Turbot level and familiarity with its interface.
The GitHub organization has been successfully imported into Guardrails.
A GitHub personal access token with the necessary permissions to create webhooks.

Step 1: Grant Permission

The personal access token used for importing an organization requires the Organization Webhooks: Read and write permission. This permission enables Guardrails to manage webhooks for capturing real-time events at the organization level.

This permission is already granted during the Required Permissions step of Importing GitHub Organization.

Step 2: Log in to Guardrails Console

Log into the Guardrails console with provided local credentials or by using any SAML based login.

Step 3: Set Up Event Handlers Policy

The GitHub Event Handlers are configured using the GitHub > Organization > Event Handlers control for each organization. This control sets up the required webhooks components for the organization.

Select the Policies tab. Search for GitHub > Organization > Event Handlers and select New Policy Setting.

Select the Resource for the imported organization, set the policy to Enforce: Enabled, and select Create.

Step 4: Check Control Status

Select the Controls tab. Search for GitHub > Organization > Event Handlers and check that the control status is OK.

Step 5: Review

Check that the control status for the respective organization is OK with the message Configured.

Verify that the webhook has been created in the GitHub organization.

Next Steps

Please see the following resources to learn more about Turbot Guardrails:

Learn more about Managing GitHub Organizations.
Explore the GitHub supported use cases in Guardrails with Policy Packs.

Troubleshooting

Issue	Description	Guide
Controls in Error	Controls may enter various states, including errors, which can impact their functionality.	Learn More About Control States
Message: `Bad Credentials`	Guardrails GitHub controls may generate errors with a `Bad credentials` message, often caused by invalid or expired tokens.	Token Expiration and Revocation
Message: `forbids access via a personal access token with fine-grained permissions`	Guardrails GitHub controls may generate this error when the personal token lacks the required permissions.	Check the required permissions at Importing GitHub Organization Required Permissions & more details at Permissions required for fine-grained personal access tokens.
Message: `Resource not accessible by personal access token .. list-users-blocked-by-an-organization`	Guardrails GitHub controls may generate this error if the personal token lacks required permissions for the organization.	Check the required permissions at Importing GitHub Organization Required Permissions & more details at Permissions required for fine-grained personal access tokens.
Further Assistance	If issues persist, please open a ticket with us and attach relevant details for more efficient troubleshooting.	Open Support Ticket