Hamster is a tool for visualising tickets from the GitHub Issues system, across all the repositories in your organisation. It uses the GitHub API (v3) to download all the tickets in the organisation, and display them under each user. Tickets are further divided into sections under each user, using a set of pre-defined labels:
- Working On: Stuff the user is currently doing. Uses the "working on" label
- On shortlist: Stuff the user is planning to work on in the near future. Uses the "shortlist" label
- Also assigned: List of tickets also assigned to the user, but not on the above list
- Recently closed: Tickets assigned to the user that were closed in the past two weeks
PLEASE NOTE: You'll have to manually create these labels (working on, shortlist) in each of the repositories within your organisation
Hamster uses local caching (currently APC) to keep some of the API response data to speed up future requests, but it has no persistent storage on its own, and it works purely off the GitHub API. The list of members in an organisation and individual user profiles are cached for 1 day, whereas the list of issues is cached for 3 minutes. Authentication happens via the GitHub oAuth API.
PLEASE NOTE: Hamster only works with GitHub organisations at the moment
- PHP 5.3+
2. Get GitHub API access
Hamster needs a valid API key to function. To get one, you need to register your application here. For the "Callback URL" field, just put the same as "Main URL" with "/auth" tagged at the end.
3/a. Deploy via Rake
There's a Rake file in place which will take care of building, configuring and deploying the Hamster application to a Linux/Apache server. It will create a new virtualhost, but you will have to create the folder the app will be copied into by hand.
PLEASE NOTE: Rake support is currently limited to RedHat-flavor Linux servers running Apache
For Rake to work, you'll need to create a configuration file by making a copy of deploy/example_rake_configfile.yaml and filling in the correct settings. The config file properties are:
- server: The hostname to use when connecting to the server via SSH
- path: Absolute path to the folder where the app should be deployed on the server
- hostname: The host where Hamster will be running (it requires a dedicated hostname for now)
- timezone: The time zone for your server. Set to "Europe/London" by default.
- github_client_id: The client id for accessing the GitHub API (provided when the app is registered)
- github_client_secret: The client secret for accessing the GitHub API (provided when the app is registered)
- github_org: The name of the GitHub organisation you're displaying
Then run rake and point it at your config file:
If you're having problems getting Rake to work, you can try deploying Hamster manually (see below)
3/b. Deploy Manually
If you don't fancy using the Rake file, or just prefer more control over your server-side setup, you can do the configuration and deployment by hand as well. All you need to do is:
- Create the cfg folder in the code base root
- Copy the contents of deploy/example_settings.json into the file cfg/settings.json
- Fill in the correct settings in cfg/settings.json (see section above for info on properties)
- Copy the contents of deploy/hamster-cron into the file /etc/cron.d/hamster-cron (make sure permissions are set to "root")
- In the cron file, replace the SERVER_USER and HOSTNAME placeholders with the cron user and the web server hostname respectively
- Copy the cfg, lib, view and webroot folders to your web server
Just open the URL of the newly set up app, which on the first run will redirect you to "/auth" for authentication. This will in turn send you off to GitHub to authorise the application to access your account (if you haven't already done so), and then send you back to Hamster.
Opening the app URL when you're logged in sends you to "/dash" which is the main dashboard page, displaying all the users and their tickets.
The list of tickets is refreshed automatically in the background every 2 minutes. The freshness of the data is displayed in the top-left corner of the app.