A powerful package to create Github Webhooks and link to Discord.js.

Discgit is a Node.js package which allows users to create webhooks on their public and private Github repos and connect them to their Discord.js bot in order to receive every notification.

Table of contents

• Installation
• Usage
• Getting started
  • Configuration
    • Config File
    • Auth Token
    • Hook Config
  • Link to Discord
  • Receiving requests
  • Fetching Embed
• Payload and Events
  • Github Events
  • Event payload
• FAQ

Installation

Using npm:

$ npm install discgit

Using yarn

$ yarn add discgit

Usage

The following examples use CommonJS import. ES6 import work the same way.

const Discgit = require('discgit');
Discgit(client)

Receiving a push event:

client.on('GithubEvent', (payload, event) => {  
  console.log(payload) // will log the information for the event
  console.log(event) // will log "push"
 });

Getting Started

Configuration

In order to create the different webhooks, the package requires a discgit.config.json file in the root folder of your project. It is very important to name the file discgit.config.json as well as putting it in the root folder.

Configuration file

The configuration file contains the different information for the Github user:

{
  "token": "Personal Access Token",
  "secret": "HTTP Request Secret",
  "port": 3000,
  "log": true,
  "repos": []
}

Key	Type	Required	Default	Description
token	string	true	null	The Personal Github Auth Token that will allow webhooks to reach the repo/organization
secret	string	false	DiscGit-WB	Secret that will be used in order to secure the different HTTP Request sent to Github and received by Github
port	number	false	3000	Port used by the HTTP server in order to listen and receive the different POST request sent by Github
logs	boolean	false	false	If the application should log the different information about the server/hooks (ping, events)
repos	Array<HookConfig	true	null	Array of the different hooks the app will listen to

Auth Token

In order for the package to access the required repos and organizations, A personal Access Token is needed in the configuration file. This token is mandatory for the package to work. The package will not store the token in a database. The package only uses the token as it is required in the different HTTP Request. To get this token, the user must create its own on this link: New Personal Access Token or by going on Github -> Settings -> Developer settings -> Personal access tokens -> New personal access token. For the package to work perfectly, few options need to be checked:

• admin:repo_hook: to be able to read and write the different repo's hooks
• admin: org_hook: to be able to read and write the different org's hooks

HookConfig

{
  "type": "repository",
  "owner": "booleans-oss",
  "repo": "DiscGit",
  "events": [
    "push",
    "start"
  ],
  "channel": "ID_CHANNEL"
}

Key	Type	Required	Default	Description
type	repository or organization	true	null	Type of repository the webhook should listen to as Organizations and Repositories hooks will behave differently.
owner	string	true	null	Name of the repository's owner or the name of the organization
repo	string	required if repository	null	The name of the repository the webhook will listen to.
events	Array<WebhookEvents>	false	['push', 'star', 'fork']	The different the webhook will listen to and send POST request when occurring
channel	string	true	null	ID of the Guild's channel the bot will send the notifications on Discord

Linking with Discord

const Discord = require('discord.js')
const Client = new Discord.Client();
// Creating a Client instance

const Discgit = require('discgit');
// Importing the package

Discgit(Client)
// Linking the bot to the package

The first and only parameter that the root function is the Client Instance. By doing so, the package will be able to declare and emit the custom event when receiving a request if the user has not defined its own event.

Receiving Requests

As the HTTP server is set up, the server will emit the event Webhook-Event on the client instance. The module allows the user to create its own Webhook-Event as long as it is declared in the bot instance. The event has two parameters:

Key	Type	Description
payload	Object[GithubPayload]	The payload sent by the Github POST Request containing the different information of the event
event	string	The event that is triggered and sent to the HTTP Server

const { fetchEmbed } = require('discgit');
client.on('Webhook-Event', (payload, event) => {
    <TextChannel>.send(`New ${event} event`)
});

However, the module offers the basic standard notification messages if the event Webhook-Event is not set by the user. The basic messages look just as the Discord's Github Webhooks messages.

Fetching default message

As the module provides a default event handler (when the event is not set), the package contains the basic message embed. It is also possible to set its own Webhook-Event but importing the default message builder in order to be able to modify it afterward.

const { fetchEmbed } = require('discgit');
// Importing the default embed builder
client.on('Webhook-Event', (payload, event) => {
    // Declaring the webhook event
    const messageEmbed = fetchEmbed(payload, event);
    // Get the default Message Embed Object
    messageEmbed.title = "Github Notification"
    // Overwriting the default title of the embed
})

Payload and Events

Github Events

The list of available events is published on Github's Webhooks API however, the default event handler only supports few of them (we will add more):

• push
• start
• fork
• pull_request
• pull_request_review
• pull_request_review_comment
• issues
• issue_comment
• release

Event Payload

The payload sent by Github's API is different for each event which is why the format of the payload will only contain the properties common to all webhooks' payload. It is recommended to check out Github's Documentation in order to find the different properties for each event's payload.

Key	Type	Description
action	string	The action of the event which depends on the event (e.g. created, closed, ...)
sender	object	The user that is responsible of the event being triggered (the pusher, or the commiter)
repository	object	The repository where the event was triggered.

FAQ

Should I commit my discgit.config.json file ?

ABSOLUTELY NOT. Your config file contains your Github Access Token. Publicly commiting your access token can compromise your whole Github profile even if you have configured it to only access hooks.

How long does the event take to reach the bot ?

The bot is directly connected to the HTTP server which means very low latency. However, latency can depend on your internet connection as well as Github API status. On average, pings take ~1 second to reach the HTTP server.

I have an error with ngrok ?

Ngrok is a NPM package which allow to connect local (127.0.0.1) servers to web servers (ngrok.io). Some firewall don't allow ngrok to link the web server to the local server. Unfortunatly, there is no solution.

How do I know what the event payload look like ?

The best advice is to look at Github's Webhook API which contains every payload for every event as they are all different. It is well-written and very easy to understand.

Can I create different webhook for the same repo ?

Unfortunatly no. The current code only allows one ngrok webhook. However, next releases involve the ability to have several webhooks for the same repo.