README

IMPORTANT UPDATE: This is no longer supported/maintained, and will most surely stop
working on Jan 27, 2012 when Pivotal deprecates the Tracker API's prior to v3. Also,
the standard GitHub-Pivotal Tracker service hook now handles everything this service
did, and in fact works better now (better handles branch commits and avoiding duplicate
comments in tracker due to merging branches).


This app is a small server to serve as a GitHub Post-Receive hook to add 
comments, and update state in Pivotal Tracker, similar to say the Lighthouse
service integration.

As of January 23, 2010, Pivotal's Tracker API itself will have some support for
doing this.  See: http://pivotallabs.com/users/dan/blog/articles/1135-pivotal-tracker-api-new-version-v3-to-be-released-on-jan-23
However, note that, as of this writing, they only support a single API token,
which means that all commits will be attributed to the Tracker member whose
token is being used in the post-commit hook.  This project solves that by
associating Tracker API tokens with GitHub users (so even if your GitHub and
Tracker emails are different that's ok), and thus you have properly attributed
comments in your Tracker stories when making a commit.

Also, many thanks to Alan Pinstein (apinstein) for his many contributions.

Configure your Tracker API key, and Project ID in a config.yml file placed in 
the same directory as this app.  It should look something like:

tracker_github_hook:
  github_url: 'http://github.com/chris/tracker_github_hook'
  tracker_api_token: a1230e72340e3babc96d5e2fab67c18d
  tracker_project_id: 123
  ref: refs/heads/master
  user_api_tokens:
    chris:
      email: chris@cobaltedge.com
      tracker_api_token: a1b2c3d4e5f67890
    alan:
      email: alan@example.com
      tracker_api_token: 0987654321abcdef
  
  
The label ('tracker_github_hook' in this case) is arbitrary and not used, it's
just their to be a useful bit of info to humans/organize the nested settings, 
and is not used.  This setup allows you to have one service that supports
multiple Tracker/GitHub projects, just define one of the above blocks for each
one, and then anytime GitHub sends a push, the service will tease out which
GitHub repo it came from and correlate that to which Tracker project you've
assigned to that.

The "ref" field is also optional; it will tell the hook to ignore commits on
any branches other than the one listed. This is useful to prevent duplication
of comments being pushed into Tracker if you have multiple remote branches.

The "user_api_tokens" is optional - the primary "tracker_api_token" will be used
by default.  But, if you do supply this block, then the hook will correlate the
email address of the author of the GitHub commit, to that within this list, and
if it finds a match, will use the specified Tracker API token.  This makes it so
that the comment in your Tracker story shows up as being made by the same person
making the GitHub commit (instead of whoever owns the default API token).

When you make commits to Git/GitHub, and want a comment and optionally a state 
update made to a story in Tracker, add the following text to your commit 
message:
    
    [Story#####]
    
or

    [Story##### state:finished]

where ##### is the story number (see the bottom of an expanded story in 
Tracker for its ID).

A commit message can have more than one [Story####] block, but the entire 
commit message will be added to both stories. The duplication is unfortunate
but better than the alternative of ignoring additional story references
altogether.

This project also requires the following rubygems:
- sinatra
- rest-client
- json


More information for, and thanks to:

Pivotal Tracker API: http://www.pivotaltracker.com/help/api
GitHub Post-Receive Hooks: http://github.com/guides/post-receive-hooks
Sinatra: http://sinatra.rubyforge.org/
RestClient: http://rubyforge.org/projects/rest-client/


TODO:
- cleanup, better testing
- support other story changes, like assigned user, etc.