GitHub Enterprise

Project owners, as well as account owners and admins, can create a GitHub Enterprise integration so that commits, pull requests and branches in GitHub Enterprise automatically attach to the appropriate stories. This replaces the old Pivotal Tracker Service Hook integrations.

Creating a new GitHub Enterprise integration

If you are a project owner, or an admin or owner of the account that includes the project, you can create a GitHub Enterprise integration for the project. Check the integration permissions for more information.

Adding a new GitHub Enterprise integration to a project

Click the INTEGRATIONS tab in your project view.
Select the Add an integration button at the top, then choose GitHub Enterprise.

Configuring the integration

Next, you’ll need to configure the integration to work for one or more projects in your account.

Naming your integration: It’s important to name the integration so that it can be easily identified in the event it needs to be edited later. For example, “Frontend GitHub Enterprise Integration”, etc.
Pivotal Tracker Projects: You’ll need to pick which Tracker projects the GitHub Enterprise integration can access. It is not necessary to set up individual GitHub Enterprise integrations for each individual project on your account.
Host URL The URL in which your GitHub Enterprise instance is hosted.
Webhook Payload URL: The payload URL is made available to you once the integration has been saved, and is the first of two pieces of information you will need to setup webhooks at the organization or repository level in GitHub Enterprise. The other item you will need is the webhook “secret token” mentioned below.
Webhook Secret Token: The “secret token” is made available to you once the integration has been saved, and is the second piece of information you will need to setup webhooks at the organization or repository level in GitHub Enterprise.

Creating the webhook on GitHub Enterprise

Navigate to the webhook creation portion of a repository or organization and fill out the form. You can also visit the setup form directly at links like:

Organization webhook location:

https://[your_host_url]/organizations/[org_name]/settings/hooks/new

Repository webhook location:

https://[your_host_url]/[org_name]/[repo_name]/settings/hooks/new

Payload URL: This can be obtained from the integration configuration page in Tracker as seen in item 3 above.
Content type: This field will need to be changed to application/json (it defaults to application/x-www-form-urlencoded).
Secret: This can also be obtained from the integration configuration page in Tracker as seen in item 4 above.
SSL verification: We recommend keeping this set to Enable SSL verification.
Which events would you like to trigger this webhook?: We recommend choosing Send me everything. At this time, the Pivotal Tracker Integration only requires the following events: Pushes & Pull Requests. However, we recommend selecting “Send me everything” so that you are automatically opted-in for future updates utilizing webhooks.
Make sure Active is selected, then click Add webhook. If everything was setup correctly, there should be a successful webhook post under the “Recent Deliveries” section.

Using the GitHub integration: Branches

Attaching branches to a story automatically

If you create a branch from the command line and include the story id in the branch name, Tracker will automatically attach a branch to the story. For example, creating a branch with the name 123123-super-cool-feature will attach it to the story with id 123123.

Using the GitHub Enterprise integration: Pull requests

Tracker will automatically attach a pull request to a story if the name of the branch that is being merged starts with that story’s ID, as described in Attaching Branches to a Story Automatically above. The PR icon’s color will match its status in GitHub:

= Open

= Closed

= Merged

= Unknown (when manually pasted into ‘Code’ field)

Using the GitHub Enterprise integration: Commits

If your project has a GitHub Enterprise integration and webhook setup, you can also attach commits to a story’s activity/comment stream by using a commit message tagged with the story id. The syntax for your commit message is pretty simple. Add the Tracker story id with a preceding hash symbol 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]

The commit message in the example below adds a commit to story 123123 and changes story state to “Finished” with the “finishes” keyword.

git commit -m "[finishes #123123] Updated settings for holograph projector"

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

You can specify multiple story ids in a commit by separating each id with a comma or space, within square brackets. However, all story ids 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 its on set of square brackets, and separate each set of brackets with a comma or space. This will prevent story ids from showing up in non-related stories.

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

Attaching GitHub Enterprise resources to your story

You can manually attach GitHub Enterprise resources to your stories using the CODE field. Simply paste in the GitHub Enterprise link to your pull request or branch, and it will be interpreted and attached.

Managing GitHub Enterprise integrations

An existing GitHub Enterprise integration can only be updated by the project owner, account owner, or admin who created the integration. Account owners and admins can delete any GitHub integrations for projects in their account. Check the integration permissions for more information.

Automate Code Review in Tracker Stories via GitHub

Prerequisites for users to automate the code review process via GitHub:

Raise user reviews via pull requests for the newly committed changes in the GitHub repository. → The appropriate Tracker user receives an email notification for the code review request from the GitHub user
While reviewing the pull request in the Github, select the appropriate review options and the saved comments as shown below
A code review is automatically created in Tracker story and an in-app notification will appear in Tracker.

Users Intention is to..	Users may choose a review action in GitHub..	Users need to choose appropriate Saved comments in GitHub..	Result in Tracker Story
Create a code review in Tracker story via GitHub	Comment	Create code review in tracker for @reviewer.	A code review is created for @reviewer
Create and approve a code review in Tracker story via GitHub	Approve	Create code review in tracker for @reviewer and pass it.	A code review is created and status is set as passed for @reviewer
Create and revise a code review in Tracker story via GitHub	Request Changes	Create code review in tracker for @reviewer and revise it.	A code review is created and status is set as revise for @reviewer

Troubleshooting Tips

We’re sorry that you’re experiencing issues with your GitHub integration, and hope the following tips and troubleshooting steps might help.

Please make sure you’ve set up an integration for GitHub Enterprise under INTEGRATIONS (as described in the Creating a new GitHub Enterprise integration section above).
The creator of the integration should make sure they’ve added all of the Projects and Repositories they expect to push and receive commits from in the GitHub Enterprise integration configuration page (INTEGRATIONS).

If all of the above looks good, please consider the following:

It is not necessary to set up individual GitHub Enterprise integrations for each individual project on your account. Any number of projects can be associated with any number of GitHub Enterprise repositories and/or organizations in a single GitHub Enterprise integration, regardless of which project you chose to start setting it up from.
Only project owners, as well as account owners/admins, can create new GitHub Enterprise integrations.
Only the user who created a GitHub Enterprise integration may edit that integration. Account owners and admins may view and delete integrations that they did not create, but they can’t edit them.

If the above does not help, please email support@pivotaltracker.com with answers to the following:

Is the issue to do with posting commit messages, attaching PRs or branches?
The project(s) where the GitHub Enterprise integration has been configured (preferably the project IDs).
The project(s) that you are having the issue with.
The story ID for a story where the commit message comment, branch or PR did not appear.
The exact commit message, PR message or branch names that were used.
The approximate time (including Time Zone) of the action.

Previous GitHub Enterprise integration (Service Hooks)

We strongly recommend that you remove any older Pivotal Tracker Service Hook integrations.

In your GitHub Enterprise repository, navigate to Settings > Integration & Services to remove them.

Learn more

The Tracker blog post announcing the new and improved GitHub integration has additional information.