@clickalicious/ci-github-bot NPM

GitHub communication bot for CI/CD workflows.

Features

Publish comments to a GitHub Pull Request by a simple method call
Comments rendered with PUG templating engine
Written in TypeScript and transpiled to JavaScript with help of Grunt
High-Quality npm package - clean & well documented code

Philosophy

If you've ever used Heroku® Review Apps and want to implement something similar for your build process then you will probably reach some point where things getting complex (like I did :). You will need to take a bunch of information and before to be able to comment on a Pull Request. This is the step which ci-github-bot claims to simplify. With its abstraction on GitHub's comment API its easy to publish the comment to the Pull Request on GitHub.

Beside it's wrapping functionality ci-github-bot provides a bridge for the CircleCI build-system. You just need to put in an username, a token. The Pull-Request URL is taken from environment variables at CircleCI. After this step you are able to communicate with Github. From now on you can publish comments to Pull Requests at GitHub. Sounds simple? It is that simple. Let's have a look at the examples ...

Example

We ship ci-github-bot with a simple bridge for passing configuration from CircleCI environment variables (ENV/.env) automagically to ci-github-bot - so the only thing left is passing username and token when creating a bot instance - the GitHub Pull Request URL is then taken from environment while building:

CircleCI

This is an example on how to use the bridge between CircleCI environment and ci-github-bot:

// Imports
const CircleCiGitHubBot = require('circlecigithubbot'); 
const ConfigurationComment = require('circlecigithubbot/configuration/comment');

// Pass GitHub username & token to new bot instance
let bot = new CircleCiGitHubBot(
    'username',
    'token'
);

// Create comment ...
bot.createPullRequestComment(
  new ConfigurationComment(
    'Hey look at the staging preview at: <a href="#{stageUrl}">#{stageText}</a>.', 
    {
        stageUrl: 'https://example.com',
        stageText: 'stage',
        buildNumber: 512,
        buildUrl: 'https://circleci.com/somebuild/somestep',
    }
  )
);

Generic Bot

If you do not use any of the built-in CI-PaaS-providers you can create a bot instance and configure it manually of course. This is also really simple for most of the use-cases as you can see below:

// Imports
const CircleCiGitHubBot = require('circlecigithubbot'); 
const ConfigurationGitHub = require('circlecigithubbot/configuration/github');
const ConfigurationComment = require('circlecigithubbot/configuration/comment');

// Bot configuration base ...
let configurationGitHub = new ConfigurationGitHub(
  'username',
  'password'
);

// Load the target/subject configuration from GitHub Pull Request URL
configurationGitHub.loadFromPullRequestUrl(
  'GitHub-Pull-Request-URL'
);

// Pass GitHub username & token to new bot instance
let bot = new CiGithubBot(
  configurationGitHub
);

// Create comment ...
bot.createPullRequestComment(
  new ConfigurationComment(
    'Hey look at the staging preview at: <a href="#{stageUrl}">#{stageText}</a>.', 
    {
        stageUrl: 'https://example.com',
        stageText: 'stage',
        buildNumber: 512,
        buildUrl: 'https://circleci.com/somebuild/somestep',
    }
  )
);

Requirements

Node.js >= 6.1

Versioning

For a consistent versioning i decided to make use of Semantic Versioning 2.0.0 http://semver.org. Its easy to understand, very common and known from many other software projects.

Roadmap

Target stable release 1.0.0
>= 90% test coverage
Implement some more bridges for popular CI-PaaS-providers like TravisCI (TravisCI please don't worry - we still love u - but you're so expensive ;)

Security Issues

If you encounter a (potential) security issue don't hesitate to get in contact with us opensource@clickalicious.de before releasing it to the public. So i get a chance to prepare and release an update before the issue getting shared. Thank you!

Participate & Share

... yeah. If you're a code monkey too - maybe we can build a force ;) If you would like to participate in either Code, Comments, Documentation, Wiki, Bug-Reports, Unit-Tests, Bug-Fixes, Feedback and/or Critic then please let me know as well!

@clickalicious/ci-github-bot v0.1.0

Table of Contents