GitHub’s service hook for Tracker

GitHub’s service hook for Pivotal Tracker makes it easy to link your commits to Tracker stories.

Setting up GitHub’s service hook

1. Decide which Tracker user’s API token you’d like to use for the service hook. It’s not an issue to use your own API token, although we typically recommend creating a “pseudo” user whose sole purpose is to pass commits to Tracker stories. You could name this user “Auto-Commits” or “Auto-Delivery,” or whatever works for you.

2. Copy the API token for the user login you’ve decided on. After signing in as that user, this can be found on the Profile page. The API token will be clearly listed at the bottom of the page.

3. Access the GitHub repository that you plan to associate with Tracker and select Settings from the menu options at the top of the page.
   

1. On the following page, select the Integrations & services option on the left.
   

1. From here, click the Add Service menu in the Services section and choose PivotalTracker from the dropdown.
   

1. You’ll see where you can paste the Tracker API token you copied earlier. The Branch field is optional, and if you leave this field empty, commit messages from all branches can be added as story comments. Otherwise, multiple branches can be specified as a space-separated list. This also includes merge commits, or when the same commits are rebased onto a different branch. If you only want to see commits that show up on master (or some other branch), put “master” in this field (capitalization counts!). It isn’t necessary to enter anything in the Endpoint field as it already points to the proper endpoint by default (the field is there in the event an override is needed).
   

Formatting your commits

Once you’ve configured the service hook, you can start tagging your commits to Tracker stories. The syntax for your commit message is pretty simple. Add the Tracker story id within square brackets at the end of your commit message. Optionally, you can include a state change for the Tracker story within the brackets. Currently, there are two state changes supported; Finished and Delivered. For example, including “Finishes” or “Fixes” in your commit message will change the specified story to the Finished state, while “Delivers” will change the specified story to Delivered state.

[(Finishes|Fixes|Delivers) #TRACKER_STORY_ID]

So, if you just fixed a CSS bug for story #109683950, your commit might look like this:

You can specify multiple story id’s in a commit by separating each id with a comma or space, within square brackets (however, all story id’s will show in the commit on all specified stories).

[#TRACKER_STORY_ID,#TRACKER_STORY_ID] or [#TRACKER_STORY_ID #TRACKER_STORY_ID]

Alternatively you can place each story id in it’s on set of square brackets, and separate each set of brackets with a comma or space (this will prevent story id’s from showing up in non-related stories).

[#TRACKER_STORY_ID],[#TRACKER_STORY_ID] or [#TRACKER_STORY_ID] [#TRACKER_STORY_ID]

When you push to GitHub, the post-receive hook will then call back to Tracker and put a comment on the story with a link to the commit on GitHub:

Troubleshooting Tips

If you find that your commits aren’t posting to your Tracker stories as expected, it’s usually related to one of the following:

• Does the Tracker API token belong to a member of the project you’re attempting to commit to? If the story ID specified in your commit is part of a project that is not accessible with that token, the commit will never be tied to the story. You may have simply forgotten to invite the token user to this project (common with newly created projects) which is easily corrected by adding the user to the project from the Project Members page.

• Often times when copying a token, extra white space can be picked up and included when pasting, which will cause the token to not be read properly. Double-check your configuration, and ensure any spaces have been removed from before or after the token.

• If you specified a branch, please check your capitalization. For instance, specifying “Master” when it should be “master” will prevent the service hook from recognizing your branch.

• Is your service hook active? If the Active check box (on the Services/Add PivotalTracker page; see screenshot in step #6) somehow became unchecked, this would cause an issue. Please check your configuration and confirm this is checked.

• The commit endpoint currently does not support emoji or emoticon characters. Please make sure any unsupported characters have not been included in your commit.

• If you’re using a private/self-hosted Github instance and it’s protected behind a firewall, you may need to open up your firewall to allow incoming requests from Tracker integrations by whitelisting our IP addresses as described here.