Skip to content

Xavisoft/pipeliner

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

10 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

pipeliner

This package helps you to create a CI/CD workflow using GitHub webhook events. You can provide scripts that will be executed when certain events happen, or add event listeners to respond to the events right in the your app. Unlike GitHub actions where you're limited to 2000 CI/CD minutes per month, webhooks are not limited. This package can also be extended if the events available are not adequate for your workflow.

Installation

npm install @xavisoft/pipeliner

Github webhook setup

Check out this link for steps on how to set up the webhooks for your GitHub organization/repository.

N.B

  1. You can set up webhooks for each repository, or for the whole organization, and this tool will handle all repositories in that organization.
  2. You can integrate more that one webhook on one Pipeliner instance.
  3. The Secret field is required for this to work. It should match the hmacSecret parameter used to create the Pipeliner instance.

Usage

Using event listeners

const Pipeliner = require('@xavisoft/pipeliner');
const child_process = require('child_process');

const options = {
   port: 8080,
   endpoint: 'webhook',
   hmacSecret: 'your_hmac_secret'
}

const pipeliner = new Pipeliner(options);

pipeliner.on('push', data) {

   const { repository } = data;

   const cmd = `
         cd ../${repository};
         git pull;
         npm install;
         pm2 restart ${repository}
   `;

   child_process.exec(cmd, (err) => {

      if (err) {
         console.error(err);
      }
   });
}

Using scripts

You can write Bash or JS scripts that runs on specific events. A script saved at path/to/scripts/git-organization/repository/eventName.js
OR
path/to/scripts/git-organization/repository/eventName.sh
will run when a certain event happens. For example we can achieve the above by creating the bash script below:

# Saved at /path/to/project/pipeline_scripts/organization/repository/push.sh

git pull
npm install
pm2 restart {repository} # restaring the app

Notifications

After every script runs, the results will be passed to pipeliner.notify(). Override the function as below to send yourself notifications:

class MyPipeliner extends Pipeliner {
   async notify(hasErred, err, output, stdout, stderr) {
      // your logic to notify yourself
   }
}

const pipeliner = new MyPipeliner(options);
pipeliner.init();

Extensibility

The list of events emitted by the package may not be enough for your workflow. That's why we included the event webhook. The event webhook is included to enable you to extend the list of events emitted by this package. It will emit all the headers and body of the request, so you can process the event as you see fit. This event is always emitted.

pipeliner.on('webhook', payload => {
   const { headers, body } = payload;
   // do your thing
});
const options = {
   port: 8080,
   endpoint: '/webhook',
   hmacSecret: 'your_hmac_secret',
   scriptsPath: __dirname + '/pipeliner_scripts'
}

const pipeliner = new Pipeliner(options);

Adding your pipeliner an existing express app

If you pass port to the Pipeliner constructor, a new express is going to be created when you call pipeliner.init(). If you have an already existing express app, you can mount pipeliner on the same app:

const expressApp = app;

const pipeliner = new Pipeliner({
   expressApp,
   endpoint: '/webhook',
   hmacSecret: 'your_hmac_secret',
   scriptsPath: __dirname + '/pipeliner_scripts'
});

NB: Make sure your express app supports the Content-Type you will have selected on your Github Webhook setup.

Pipeliner

The Pipeliner class creates objects that listens to GitHub webhooks and emit events

Kind: global class
Emits: push, pull_request, merge, release, new_branch, new_tag, unauthorized_webhook

new Pipeliner(options)

Param Type Description
options object
options.expressApp object an express application (created by require('express)())
options.port object The port to make the express application listen to. Only used when options.expressApp was not passed
options.endpointPath object The path the webhook events will be posted by GitHub
options.scriptsPath object The path where scripts that response to events are stored
options.hmacSecret object The secret used to verify if GitHub really sent the webhook events, not some ill-intended party

pipeliner.notify(hasErred, err, output, stdout, stderr)

To be overidden. It will be called when a script is finished with the output from the script

Kind: instance method of Pipeliner

Param Type Description
hasErred boolean indicates whether the command ran successfully
err Error The error that occured. null if hasErred is false
output string both stdout and stderr logs
stdout string stdout log
stderr string stderr log

pipeliner.init() ⇒ Promise

This method initialize the pipeliner to start listening for webhook events

Kind: instance method of Pipeliner

pipeliner.stop() ⇒ Promise

This method stops the Pipeliner instance from listening to webhook events

Kind: instance method of Pipeliner

"new_tag"

Emmitted when a new tag is created on a repository

Kind: event emitted by Pipeliner
Properties

Name Type Description
organization string GitHub organization name
repository string GitHub repository name
originalPayload object Original data send by GitHub
data object
data.tag string Name of the tag created
data.branch string The branch on which the tag was created

"new_branch"

Emmitted when a new branch is created on a repository

Kind: event emitted by Pipeliner
Properties

Name Type Description
organization string GitHub organization name
repository string GitHub repository name
originalPayload object Original data send by GitHub
data object
data.branch string Name of branch that was created

"release"

Emmitted when a new release is created on a repository

Kind: event emitted by Pipeliner
Properties

Name Type Description
organization string GitHub organization name
repository string GitHub repository name
originalPayload object Original data send by GitHub
data object
data.branch string Name of branch the realease was created from
data.tag string Name of tag the release was created from

"push"

Emmitted when changes are pushed to a repository

Kind: event emitted by Pipeliner
Properties

Name Type Description
organization string GitHub organization name
repository string GitHub repository name
originalPayload object Original data send by GitHub
data object
data.branch string Name of the branch the changes were pushed to

"pull_request"

Emmitted when a pull request is made

Kind: event emitted by Pipeliner
Properties

Name Type Description
organization string GitHub organization name
repository string GitHub repository name
originalPayload object Original data send by GitHub
data object
data.branch string Name of branch requesting to be merged
data.base_branch string Name of branch the changes are supposed to be merged to

"merge"

Emmitted when two branches are merged

Kind: event emitted by Pipeliner
Properties

Name Type Description
organization string GitHub organization name
repository string GitHub repository name
originalPayload object Original data send by GitHub
data object
data.branch string Name of branch that was requested to be merged
data.base_branch string Base branch

"webhook"

This events has all the headers and body from GitHub. You can extend the capabilities using this package by listening to this event

Kind: event emitted by Pipeliner
Properties

Name Type Description
headers object Headers sent by GitHub
body object The body of the request send by GitHub

"unauthorized_webhook"

This event is emitted an unauthroized client tries to send a webhook event

Kind: event emitted by Pipeliner