GitHub integration

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.

Creating a new 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.

Adding a new GitHub Integration to a project

  1. Click the MORE tab in your project, then choose Integrations in the sidebar.
  2. Select the Add an integration button at the top, then choose GitHub.
  3. Next you’ll need to connect your GitHub account to Pivotal Tracker. Click the Authenticate your GitHub account button.
  4. The GitHub integration requires write access to the repository and organization webhook permissions to manage the installation of webhooks. Select Authorize pivotaltracker.
    GitHub OAuth Consent Screen

Configuring the integration

After connecting Pivotal Tracker to Github, you’ll need to configure the integration to work for one or more projects in your account. You’ll also select the organizations and/or repositories that should have access to these projects.

Configure GitHub integration

  1. Title and Description: It’s important to name and describe the integration so that it can be easily identified in the event it needs to be edited later. For example, “Frontend GitHub Integration”, etc.

  2. Pivotal Tracker Projects: You’ll need to pick which Tracker projects the GitHub integration can access. It is not necessary to set up individual GitHub Integrations for each individual project on your account.

  3. GitHub Organizations and Repositories: You can either pick individual repositories or all repositories under an organization. You’ll need admin access to the GitHub repository or organization.

Authenticating to use the integration

Once an integration’s been created by a project owner, each project member will need to authenticate through GitHub to see existing, as well as create new, Branches and Pull Requests on stories. They can do so from either their Profile page or directly from within a story (if there are existing Branches or PRs on the story).

To authenticate from the Profile page

  1. After signing in, click Profile under your username/avatar, at the top right of your Tracker window.
  2. Scroll to the AUTHORIZED APPLICATIONS section at the bottom of the page.
  3. Select the Authenticate your GitHub account button and sign in to your GitHub account.
  4. The GitHub integration requires write access to the repository and organization webhook permissions to manage the installation of webhooks. Select Authorize pivotaltracker.

To authenticate from within a story

When there are existing Branches and/or Pull Requests on stories, unauthenticated project members will see a message that says This story has attached GitHub content under the labels section, along with an adjacent Authenticate with GitHub button, so they can easily authenticate directly from within the story.

Using the GitHub integration: Branches

GitHub branch on a story

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.

Configure GitHub integration

Using the GitHub integration: Pull requests

Code section with Pull Request

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 name of 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.

Authorize with GitHub to see more information

When a story is opened, the latest state of the PR is fetched. Tracker displays an aggregated state of the PR of mergability, status checks, and code reviews. If everything is passing, it will go green. If one or more 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.

Pull Request

Select the desired repository and then choose a pull request to attach.

Using the GitHub integration: Commits

GitHub Commit

If your project has a GitHub integration, 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:

Example of syntax for tagging your commits to Tracker stories

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]

Commits can also be attached manually by clicking the paperclip icon in a comment and selecting GitHub Commit from the dropdown menu.

Attachment menu for comment

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.

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 and authenticated an integration for GitHub under MORE > Integrations (as described in the Creating a new GitHub integration section above).
  • If you’re unable to see existing Pull Requests (PRs) and Branches on stories, please make sure you’ve authenticated via GitHub by either clicking the Authenticate with GitHub button from within the story, or from your Profile page (as described in the Authenticating to use the 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 Integration Configuration page (MORE > Integrations).
  • Within GitHub, please ensure that the Organization you want to connect to via an integration allows third-party access to Pivotal Tracker under Settings > Third-Party Access.

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

  • You just need to authenticate once in order to take advantage of the GitHub features we have. It’s a per-user function, not per-project.
  • Viewers cannot ever see Pull Requests / Branches on stories as they cannot authenticate via GitHub within Tracker.
  • It is not necessary to set up individual GitHub Integrations for each individual project on your account. Any number of projects can be associated with any number of GitHub repositories and/or organizations in a single GitHub 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 Integrations.
  • Only the user who created a GitHub 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 tracker@pivotal.io with answers to the following:

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

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.

Learn more

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

Previous
Source Control Management (SCM)
Next
GitHub’s service hook for Tracker