Hubstats Build Status

Hubstats is a rails plugin which allows you to search and monitor pull requests, teams, and users made across a collection of repositories. It also gives extra statistics about users, teams, and pull requests not found on GitHub. For more information on Hubstats and the development of Hubstats, see the Coding in the Crease Hubstats blog by Emma Sax. For additional information on the setup process of Hubstats, although you'll find plenty below, go to the Hubstats wiki.

Setup

The following setup is designed to only be used when integrating this plugin into a rails application.

Run rails generate hubstats:install.

Configure octokit.yml with your GitHub information (see below).

Run rake hubstats:install:migrations.

Run rake hubstats:setup to run the necessary migrations and start pulling data from GitHub.

Add 'mount Hubstats::Engine => "/hubstats"' to your apps routes file.

Configuration

Authentication

Hubstats needs GitHub credentials to access your repositories, these can be setup in one of two ways:

GitHub API Tokens

Add your GitHub API token (called access_token) to octokit.yml.

Environment Variables

Hubstats can also use OAUTH access tokens stored in ENV["GITHUB_API_TOKEN"] if for some reason you don't want to store them in octokit.yml.

Configuring Data to be Received from GitHub

Organizations to Follow

Hubstats tracks certain repositories and teams that are part of an organization. Therefore, you must whitelist the specific GitHub organization to track in octokit.yml. The list of organizations should look something like this:

org_name:
 - sportngin

Repositories to Follow

If you only want Hubstats to watch certain repositories, you can set it to watch a list of specific repositories in octokit.yml. Otherwise, the default will be for Hubstats to watch an entire organization's list of repositories. The list of repositories should look like either:

repo_list:
 - sportngin/repo_one
 - sportngin/repo_two
 - sportngin/repo_three

Teams to Follow

If you want Hubstats to watch certain teams to give back GitHub team metrics, then you must whitelist a list of teams in the octokit.yml. If no list of teams is added, then there will be no team metrics. The list of teams should look something like:

team_list:
 - Team One
 - Team Two
 - Team Three

Also, the GitHub API token in octokit.yml must be a member of all of the teams listed in order to receive webhooks and populate team data.

Users to Ignore

If there are specific users that should not show up on any lists or in any metrics, then they can be placed on the ignore_users_list part of the octokit.yml. This list is referenced when making the list of users in teams. The list of users to ignore should look like:

ignore_users_list:
 - user_login_one
 - user_login_two
 - user_login_three

Webhooks

Hubstats uses GitHub webhooks to keep its data updated. It requires you to set a secret as well as an endpoint to push to.

To generate a secret run:

 ruby -rsecurerandom -e 'puts SecureRandom.hex(20)'

Set the endpoint to be:

www.yourdomain.com/hubstats/handler

Testing

All of the automated tests are written in RSpec. To run these tests, run the following commands, assuming that there are two already existent local databases titled hubstats_development and hubstats_test:

cd test/dummy/
rake db:test:prepare
bundle exec rspec

To test what Hubstats would actually look like on a web browser, we need to install the plugin into a Rails application to run. This is because Hubstats is a plugin, not an application. The test directory is also a dummy rails application for manually testing the UI by serving Hubstats locally. When developing and using the test/dummy locally, then the test will automatically sync with any updated code, so it doesn't need to be re-served when changes are made with the normal Rails application. When in the development process, one just needs to run:

cd test/dummy/
bundle exec rails s

to serve the plugin. http://guides.rubyonrails.org/plugins.html will give more information on the implementation of a Rails plugin.

TL:DR

Run rails generate hubstats:install.

Configure octokit.yml with your GitHub information (see above).

Run rake hubstats:install:migrations.

Run rake hubstats:setup.

Add 'mount Hubstats::Engine => "/hubstats"' to your routes file.

Read this blog about Hubstats.

Go to the Hubstats wiki for additional information.

This project rocks and uses MIT-LICENSE.