Project owners can create a GitHub integration so that commits, pull requests and branches in GitHub automatically attach to the appropriate stories and epics. This replaces the old Pivotal Tracker Service Hook integrations. In addition, whether or not a project has a GitHub integration set up, project members can manually attach commits, pull requests and branches to stories and epics.
How to create a GitHub integration
If you are a project owner, or an admin or owner of the account that includes the project, you can create a GitHub integration for the project. Check the integration permissions for more information.
To add a new GitHub Integration to a project, click the Settings tab in your project, then choose Integrations in the header.
Connect your GitHub account
When adding the integration, you first need to connect your GitHub account to the Pivotal Tracker app.
The GitHub integration requires write access to the repository and organization webhook permissions to manage the installation of webhooks.
It’s important to name the integration with a Title so if you need to edit it you can remember which one was setup. For example, “Frontend GitHub Integration”.
You’ll need to pick which Pivotal Tracker Projects the GitHub integration can access.
On the GitHub side, you can either pick individual repositories or all repositories under an organization. You’ll need admin access to the GitHub repository or organization.
Using the GitHub integration
Attaching branches to a story manually
In your Tracker story, click on Attach from GitHub, and copy-paste your GitHub branch link into the section titled Attach a GitHub Link.
Attaching branches to a story automatically
If you create a branch from the command line and include the story or epic id in the branch name, Tracker will automatically attach a branch to the story or epic.
For example, creating a branch with the name
123123-super-cool-feature will attach it to the story with id 123123.
Creating branches from Tracker
To create a branch from your Tracker story or epic and attach it automatically, pick the Branch option in the “Code” section dropdown menu.
From there, select a repository. An editable text field will appear with an auto-generated branch name. Change the branch name if desired, and click Create. You can copy the command to check it out on the command line. After closing the modal, you can click the branch actions menu to the right of the branch name to copy the branch name.
You can attach a pull request (PR) to your Tracker story manually.
Tracker will automatically attach a pull request to a story or epic if the branch that is being merged starts with that story or epic’s ID, as described in Attaching Branches to a Story Automatically.
Tracker will show the state of a PR for a given story. If you have not yet connected your Tracker user login to GitHub, you can click on the PR in the Tracker story to authorize it and be able to see PR states.
When a story is opened, the latest state of the PR is fetched. We display an aggregated state of the PR of mergability, status checks, and code reviews. If everything is passing it will go green, if one of those checks fails then the whole PR will show as failed.
Attaching a PR Manually
To attach a PR from your Tracker story or epic, pick the Pull Request option in the “Code” section dropdown menu.
Select the desired repository and then choose a pull request to attach.
If your project has a GitHub integration, you can also attach commits to a story’s comment stream by using a commit message tagged with the 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"
Commits can also be attached manually by clicking the paperclip icon in a comment and selecting GitHub Commit from the dropdown menu.
Managing GitHub integrations
An existing GitHub integration can only be updated by the project owner or 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.
Disconnecting GitHub authorization from your Tracker login
If you no longer want your Tracker login authorized to access your GitHub webhooks, repositories and organization, you can disconnect it. Click on your user name at the top right of your browser window and choose Profile. Scroll down to the Authorized Applications section. Click the Disconnect button and click OK in the confirmation popup. Alternatively, you can click Manage on GitHub to update access there.
Previous GitHub integration (Service Hooks)
We strongly recommend that you remove any older Pivotal Tracker Service Hook integrations.
In your GitHub repository, navigate to Settings > Integration & Services to remove them.
The Tracker blog post announcing the new and improved GitHub integration has additional information.