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.
    The 'settings' tab available on the GitHub repository page

  4. On the following page, select the Integrations & services option on the left.
    The Webhooks & Services link on the left side of the Settings page in GitHub

  5. From here, click the Add Service menu in the Services section and choose PivotalTracker from the dropdown.
    Selecting a service to add from the 'add service' dropdown in GitHub

  6. 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).
    Token, branch, and endpoint entry for the Pivotal Tracker service in GitHub

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:

Example of syntax for tagging your commits to Tracker stories

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:

Example of a commit message appearing in Tracker

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.

Previous
Source Control Management (SCM)