This directory contains the Github webhook for verifying that all
commits on an ofiwg PR contain a "Signed-off-by" line, and its
relevant configuration.

The bot runs as a Ruby Sinatra server on flatbed.openfabrics.org.  It
was initially heavily inspired by
http://git-scm.com/book/en/v2/GitHub-Scripting-GitHub.

The original flatbed server was running RHEL (CentOS, actually, but
close enough).  As of Feb 2016, it is now Ubuntu.  So this README
shows info about both Ubunutu and RHEL (mainly for hysterical
raisins).

===================

RHEL background:

Sadly, I did not take good notes about how to get Sinatra installed on
Flatbed.  Looking on flatbed on 17 Feb 2016, I see the following RPMs
installed:

- rubygems
- rubygem-sinatra

These seem to be the key RPMs to install.  Hopefully, they're in the
CentOS yum repo -- I do not have any notes on where I got them from.
The following RPMs seem to be dependencies of Sinatra; hopefully yum
just pull them in:

- rubygem-crack
- rubygem-daemons
- rubygem-rack-test
- rubygem-httparty
- rubygem-eventmachine
- rubygem-thin
- rubygem-rack
- rubygem-json

Ubuntu backgruond:

On Ubuntu, it was straightforward to install the Sinatra server:

# apt-get install ruby-sinatra ruby-htttparty

===================

There are several important files in this directory:

1. github-webhook-ofiwg-init.d-rhel and
   github-webhook-ofiwg-init.d-ubuntu

The /etc/init.d/github-webhook-ofiwg (one for RHEL and one for Ubuntu)
script that starts and stops the Ruby Sinatra server script that
actually listens for the incoming Github webhook pings.

2. verify-signed-off.rb

The Ruby Sinatra server (i.e., a Ruby script that uses the Sinatra
framework for listening for incoming HTTP requests) that listens for
Github webhook pings.  When it gets an incoming ping, if it's for a
pull request, the script gets a listing of all the commits on that
pull request and verifies that they all have a "Signed-off-by" line in
them.  If they all do, all commits have a "success" status set (at
Github).  If any are missing this line, then those commits have a
"failed" status set, and the last commit on the PR also has a "failed"
status set (because Github shows the overall status of the PR as the
last commit's status).

Every time commits are pushed to the PR, all the commits will be
checked again.  This ensures that even if you replace all the commits,
we'll check them all (it's one HTTP request to get all the commit
messages, anyway, so it's not like it makes the check take
significantly longer).

Note that the Ruby Sinatra server listens on localhost port 5000; it
is not directly accessible to the outside world.

On flatbed.openfabrics.org, the file is located in:

RHEL: /var/www/github-webhooks/ofiwg/verify-signed-off.rb
Ubuntu: /var/www/html/github-webhooks/ofiwg/verify-signed-off.rb

3. apache-config.txt

This is a snipit from flatbed.openfabrics.org:

RHEL: /etc/httpd/conf.d/20-ssl.conf
Ubuntu: etc/apache2/mods-enabled/proxy.conf

This snipit is inserted in the SSL version of www.openfabrics.org
config to enable the reverse proxy (i.e., incoming web requests to
https://www.openfabrics.org/github-webhooks/ofiwg get routed
internally to http://localhost:5000/ -- i.e., the Ruby Sinatra
server).

On Ubuntu, I had to load the mod_proxy Apache module by:

# a2enmod proxy
# a2enmod proxy_http
# cd /etc/apache2/mods-enabled
# ln -s ../mods-available/proxy.conf
        ^^ This is the file to add the apache proxy config

===================

There is one additional file needed on flatbed.openfabrics.org:

RHEL: /etc/sysconfig/github-webhook-ofiwg
Ubuntu: /etc/default/github-webhook-ofiwg

The init.d script will source this file; it needs to set an
environment variable that verify-signed-off.rb will look for:
$GITHUB_AUTH_TOKEN.

Specifically, this file should contain a line like this:

export GITHUB_AUTH_TOKEN="...the token..."

(this file is not here in the git repo, of course -- because then
everyone could see our auth token!)

A Github auth token can be obtained from
https://github.com/settings/tokens of a user who has commit access to
the target Github repo(s).  The token needs to have the following
permissions when you create it:

- repo
- public_repo
- repo:status