GitHub Application

​

Getting Started

To start using the Keep GitHub Application, follow these simple steps:

1. Sign up and log in to the Keep’s platform.

2. Install the Keep GitHub Application either through the onboarding screen or by visiting this link. The installation process is straightforward and user-friendly.

   

3. Connect your preferred provider, such as Datadog, by linking it to Keep’s platform. This step allows Keep to seamlessly generate and deploy alerts to your chosen provider.

   

4. You are now ready to go! The Keep GitHub Application is successfully integrated into your GitHub workflow.

​

How does it work?

The Keep GitHub Application operates seamlessly in the background, ensuring that you stay informed about relevant changes in your repositories. Whenever a pull request is opened or updated, the application monitors the files under the .keep/ directory.

Once a change is detected, the GitHub application sends an HTTP request to Keep’s API smart AI layer. The AI layer analyzes the content of the changed files and together with context from the provider (existing alerts, sample logs, etc.) generates an alert based on the user provided plain English description. The AI-powered alert generation ensures accuracy and relevance.

After the alert is generated, the Keep GitHub Application automatically comments the alert on the respective file within the pull request. This allows you, as the user, to conveniently review and verify the generated alert.

If the generated alert meets your requirements and is ready to be deployed, you can simply leave a comment on the file. The comment should include one of the predefined emojis, such as 🚀 or 🆗 (refer to the “Deploying Alerts with Emojis” section). The Keep GitHub Application recognizes these emojis as commands to proceed with the deployment process.

This intuitive workflow streamlines the alert generation and deployment process, providing you with a seamless experience and allowing you to focus on the core aspects of your project.

​

Monitoring Files Under .keep/ Directory

The Keep GitHub Application actively monitors the files residing within the .keep/ directory located at the parent level of your repository. Any changes or updates made to these files will trigger the alert generation process. This allows you to focus on the essential aspects of your project while ensuring that relevant changes are promptly identified and acted upon.

​

Alert File Structure

Each file under the .keep/ directory represents a single alert. The structure of an alert file follows the YAML format. Below is an example of an alert file:

# The alert text in plain English
alert: |
  Count the error rate (4xx-5xx) this service has in the last 10 minutes.
  Alert when the threshold is above 5% out of total requests.
  Send a Slack message to the #alerts-playground channel and include all the context you have"

# The provider you've previously connected and want this alert to be generated for
provider: datadog
# You can use this to override Keep's managed API and have the GitHub application
# use the API that you run locally (using the NGROK URL)
# api_url: https://OVERRIDE-KEEP-MANAGED-API

The alert file consists of the following components:

1. Alert Text: This section contains the plain English description of the alert. Write a clear and concise explanation of the conditions or criteria that should trigger the alert. You can include any relevant context to facilitate understanding and resolution.

2. Provider: Specify the provider to which you want the alert to be generated. This ensures that the alert seamlessly integrates with your existing monitoring and notification infrastructure. In the example above, the alert is configured to be generated for Datadog.

3. API Override: Optionally, you can include the api_url field to override Keep’s managed API. This allows you to use your locally hosted API for advanced customization and integration purposes.

{
    "asctime": "0000-00-00 00:00:00,000",
    "message": "ngrok tunnel: https://fab5-213-57-123-130.ngrok.io",
    ...
}

​

Deploying Alerts with Emojis

To deploy an alert to the specified provider, you can simply leave a comment on the respective file using the 🚀 or 🆗 emojis. The Keep GitHub Application recognizes these emojis as commands and will initiate the deployment process accordingly. This streamlined approach ensures a smooth and intuitive experience when deploying alerts.

For example, by leaving a comment with the 🚀 emoji, you can signal the Keep GitHub Application to deploy the alert to the specified provider (Datadog in our example above).

The Keep GitHub Application will either mark the comment with 👍 meaning the alert was successfully deployed or 👎 and another comment with the failure reason in case the alert was not deployed.