A Guide to 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

Step 1. Decide which Tracker user’s API token you’d like to use for the service hook. Typically we advise to create a ‘pseudo’ user whose sole purpose is to pass commits to Tracker stories. You could name this user “Auto-Commits” or “Auto-Delivery,” whatever works for you.

Step 2. Next, grab 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. Just click the username in the upper right, and choose Profile from the dropdown. The API token will be clearly listed at the bottom of the page.

Step 3. Then, access the GitHub repository that you plan to associate with Tracker and click the Settings link located along the right-hand side menu. 

Step 4. On the following page, select the Webhooks & Services page on the left. 

Step 5. From here, choose the Add Service button located in the Services section and select PivotalTracker from the dropdown.

Step 6. In the final step, you’ll see where you can enter the Tracker API token you grabbed earlier. The Branch field is optional and if you leave this field empty, commit messages from all branches can be added as story comments. 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).

Now you’re ready to start committing! But be sure to test it out to make sure everything’s working as expected. For more in-depth information on the workflow between GitHub and Pivotal Tracker, check out Ian Zabel’s blog post, Level up Your Development Workflow with GitHub and Pivotal Tracker.

Troubleshooting Tips

Whether you’re new to the GitHub service hook for Tracker or you’ve been using it for a while, 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.
• Oftentimes when copying a token (or anything, really), 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 cause the service hook not to recognize your branch.
• Is your service hook active? If the Active check box (on the Services/Add PivotalTracker page; see screenshot in step #5 above) somehow became unchecked, this would cause an issue. Please check your configuration and confirm this is checked.

We hope this helps; however, if none of these tips explains an issue you’re experiencing, feel free to email our support at support@pivotaltracker.com—we’re happy to assist. Note: be prepared to provide a specific story ID that your commit failed to make it to, so we can scan our logs for clues.

Happy Tracking!