discgit v1.1.1

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": []
}

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"
}

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:

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.

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.