Home

Welcome to the github_bot-ruby wiki!

Overview

The GitHub Bot project is the starting point for Ruby-based GitHub bot creation. The key items this project provides to consumers are

• Generic or application specific webhook mounted routes
• Octokit API configuration via Railtie
• Base classes for both your tasks and validators

Configuration

With creating a new GitHub application, there are a few bits of information you will have to take note of. These items are as follows and mapped to the corresponding ENV variables

GitHub Information	ENV Variable
App ID	GITHUB_APP_IDENTIFIER
Webhook Secret	GITHUB_WEBHOOK_SECRET
Private Key	GITHUB_APP_PEM

Incoming Requests

There are two ways consumers may accept incoming webhook request. The first is through the generic webhook endpoint. The second is by defining a path specific endpoint for the validator.

The webhook Route

The base webhook route provides the ability to define and utilize an .github-bots configuration file at the root of the project. This file will look something like the following:

---
pull_request:
  - ApplicationConfigBot::Validator

What this allows is for a GitHub project to utilize numerous GitHub bot validators for one repository. Each 'validator' that is defined must have a class method called validate which is the generic entry point into the bot's validation of the current pull request.

Application Specific Route

It is a very good idea to create an application specific route because there will come a day that you want to be able to test your application against a forked repository without having to pull everyone else's code just to perform your development. Building on the validator noted previously, we've added to the config/routes.rb the following entry within the webhook namespace

ApplicationConfigBot::Engine.routes.draw do
  namespace :webhooks do
    post 'application-config', action: :validate, controller: 'application_config', defaults: { format: :json }
  end
end

# Adding this to mount the above routes into the application level in order to be able to use
# the path helpers without having to access them with the main_app.
Rails.application.routes.draw do
  mount ApplicationConfigBot::Engine => '/' if ApplicationConfigBot.draw_routes_in_host_app
end

Now the validate method on the controller looks very straightforward to what was being executed by the generic route

def validate
  return unless pull_request? || check_run?

    ApplicationConfigBot::Validator.validate
  rescue StandardError => e
    Rails.logger.error message: 'Application Config Bot failure', exception: e
    raise
end

Base Classes

Validator

The validator is the parent controller for all actions that should take place against the repository. It will keep track of the GitHub Check Run, feedback provided, and a few other useful helper methods.

Tasks

The tasks can be the workhorses of your validation. Its not necessary but its a nice touch in how you may structure your logic on how steps are taken to validate your content. The task does have a concept of hierarchy to its validator so it is required to initialize the task with the validator that invoked it. All requests to the task are then funneled back up to the validator for processing such as providing feedback.

Example

Here is an example of how your Validator that extended the GithubBot::Validator::Base class could look

def validate
  check_run(name: 'Application Configuration') do
    # set the check run to in progress
    in_progress

    # perform validation steps
    ...
  end
end

The check_run block create a GitHub Check Run utilized for providing checked responses to your changes in the repository. The block initially creates the check run in a 'queued' status hence why at a point you must note you're 'in process' of performing your validations. Upon ending the block, the base class will evaluate if any feedback was provided to the check run and if so, it will complete the check run requesting action from the requestor; otherwise, the check run is completed to with a success response.

Testing

To start, remember that your configuration to the webhook endpoint resides within the GitHub bot application itself. This mean, you are unable to change this endpoint without impacting 'production' usage. So you ask how do I test then? In order to develop, you will have to create your own GitHub app and delivery the webhook to your local machine. Rather than exposing these 'test' applications to the public, create your application within your user's organization. That way, you may create your own repository within your user's organization to attach the bot validator. You should then be able to rackup your code provided you've configured the env.list with your app's information.

Webhook URL

Now testing, the webhook URL will look something like this

http://10.153.39.82:3000/webhooks/application-config