@calmdownval/bob

Bob

A simple local(host) builder who likes to listen to GitHub webhooks.

Usage Guide

1. Install Bob

You will also need to install the Signal peer dependency.

# using NPM
npm install @calmdownval/bob @calmdownval/signal

# using Yarn
yarn add @calmdownval/bob @calmdownval/signal

2. Register GitHub Webhooks

This package is intended to be used on localhost without the need for any public endpoints. This is possible using proxy services like smee.io. Once you have a channel ready use that as your webhook URL.

Make sure to set a proper secret when registering webhooks. It is an optional feature, but when using a proxy it is the only reliable way to ensure that events you receive are in fact from GitHub.

3. Create a Listener

Create a new instance of the Listener class with configuration to suit your needs.

You can use the tls key to pass through any options accepted by NodeJS' TLS Socket, typically certificates or rejectUnauthorized for development environments.

import { Listener } from '@calmdownval/bob';

const listener = new Listener({
  secret: '<your-secret>',
  sourceURL: '<webhook-proxy-url>',
  tls: {
    rejectUnauthorized: false
  }
});

4. Bind Event Handlers

Assign event handlers using the Signal library to signals provided by the Listener instance. The handlers receive unmodified event payloads as they are received from GitHub. You can find their definitions here.

import * as Signal from '@calmdownval/signal';

Signal.on(listener.event<any>('push'), ({ data: e }) => {
  console.log(`${e.sender.login} pushed ${e.commits.length} commits into ${e.repository.full_name}.`);
});

The event method of the Listener class returns a signal triggered when the GitHub webhook specified by the first argument is invoked. If you omit this argument or use the Listener.ANY_EVENT constant you will receive a signal that triggers on any GitHub webhook received. This is useful if you wish to switch between event types manually.

Using the type argument of the event method you can inject typings of the event. GitHub webhook typings are out of scope of this library, instead consider using @octokit/webhooks-definitions.