GitHub Issues
Overview
GitHub Issues provides developers with issue tracking functionality directly from within GitHub. Teams using GitHub Issues need a way to prioritize, track, and work on these issues. Planview Hub works with both hosted and on-premise GitHub Issues to synchronize issues into the development team’s Agile planning tools. With the issue represented in two systems, information on the artifact needs to be kept up to date. Teams also need to be able to communicate with the individuals who created the issue. Planview Hub accommodates these needs.
For Example:
- If someone submits an issue in GitHub, the development team will see the issue and its metadata within their Agile tool (for example, Jira).
- They can then prioritize and plan as they see fit, and communicate with the submitter via comments.
- When the issue in Jira is completed, the corresponding issue in GitHub is closed, so everyone knows the work is completed.
Key Features and Benefits
- Synchronizes GitHub Issues to Agile planning tools
- Allows GitHub labels to synchronize to Agile planning tools
- Allows developers to communicate via comments
- Ensures submitters are aware of the status of their issues
- Allows issues to be generated in developers' system of choice while enabling the team to plan effectively in an Agile planning tool
- Gives developers the ability to better plan and prioritize issues
- Facilitates automated communication within teams
Common Integration Patterns
- Sharing Stories and Defects between Dev and Test
- Agile Planning SLI Pattern: Issues are created in GitHub, but Agile teams want to have finer-grained control over planning and scheduling of these issues. Issues are brought into Agile planning tools so that this is possible.
Connector Setup Details
This section describes the basic steps needed to prepare your GitHub instance for use with Planview Hub. Note that additional fields for synchronization or configuration of queries may be required depending on the requirements of your integration.
Minimal User Permissions & Planview Hub User
We recommend that you create a new user within your external tool, to be used only for your Planview Hub integration. This is the user information you will enter when setting up your repository connection within Planview Hub. By creating a new user, you will ensure that the correct permissions are granted, and allow for traceability of the modifications that are made by the synchronization.
In general, your user account should have sufficient permissions to create, read, and update artifacts in your repository. However, depending on the use case, your user may need different permissions. For example, if you are only interested in flowing data out of your repository, your user may not need to have full CRUD access, as the 'create' and 'update' permissions may not be needed.
Your user should have a secure password or token. Please be aware that Planview Hub will not allow you to save a repository connection utilizing a weak password/token, such as 'tasktop.'
See instructions on how to create a new user in Github.
List of minimal user permissions:
- A GitHub user with Pull Access (write access) to the to project(s) being synced.
- User is an either an owner, collaborator, or organization member of the repository.
Connecting to the GitHub Issues Repository
Standard Authentication
Required Fields:
- Location/Connection URL
- URL Format (On Prem): http://someServer/
- URL Format (On Demand/Cloud): https://api.github.com/
- Username
- Password
Optional Fields:
- Throttling Settings: This field indicates the number of API calls that can be made per minute. See details here.
- Note: This field should only be set under the guidance of customer care as the ideal value is highly dependent on each customer's unique environment.
- Connection Security: If checked, insecure connections to this repository will be allowed. See details here.
Personal Access Token
Planview Hub: 19.3 and later
Tasktop Sync: 4.19 and later
Required Fields:
- Location/Connection URL
- URL Format (On Prem): http://someserver/
- URL Format (On Demand/Cloud): https://api.github.com/
- Personal Access Token
SSO Authentication
Additionally, GitHub Issues supports the following SSO implementations:
- Script (HTTP cookies)
- X.509 Certificate
Learn more about how to set up your repository in Planview Hub here.
Creating a Proxy Association Attribute (Tasktop Sync)
What is Proxy Association Attribute?
A custom string attribute is recommended to be used as the proxy association storage. Tasktop Sync needs to keep track of the association between a task and its proxy task. The association is persisted in a proxy store allowing the synchronization to be restored if there is any catastrophic failure of Tasktop Sync.
A proxy association attribute must be created for each artifact type to be synchronized.
The Proxy Association Attribute field must be a text/string type field in your ALM repository. We recommend creating this field with the name "Tasktop Sync Proxy."
When working with GitHub connector, choose to use Database based proxy.
Initialization and Changes Queries (Tasktop Sync)
Tasktop Sync uses queries in the ALM systems to determine the artifacts to synchronize and detect changes in the system.
The initialization query represents the full set of artifacts to synchronize and is only run on initial configuration or manually.
The changes query should be defined the same as the initialization query but include some time scoping information (e.g. last 7 days) as this is the query that is executed on the defined schedule to detect changes. In many cases, these queries can be defined in the ALM system, providing the power of the built-in filters to properly scope the synchronization. If this is not possible, Tasktop Sync provides other mechanisms for filtering items in scope.
GitHub Issues connector allows returning issues based on a particular repository.
|
Query |
Instruction |
|---|---|
|
Initialization Query |
Select Repository based query and choose the repository to retrieve artifacts from
|
|
Changes Query |
Use the same query as in the previous step. |
Other Configuration Settings
Person Reconciliation
For field based (advanced) person mapping/reconciliation scenarios, you can choose to use any of the following person object fields.
- Available fields: person-username, person-email, person-id, person-display-name
- Default: person-id
Default person ID is your log in username.
Learn more about how to configure person reconciliation in Planview Hub here.
Full Scan
In general, a full scan is not required to synchronize updates from this repository. However, it is possible that some read-only fields may require a full scan. Please consult with customer care for additional details.
Supported Features
Special Features Supported
|
Feature |
Custom Type Supported? |
Applicable Planview Hub Versions |
Applicable Repository Versions |
|---|---|---|---|
|
|
|
|
|
|
|
N/A |
Planview Hub: All Tasktop Sync: 4.0 and later |
Any supported repository version: |
|
|
|
|
|
|
N/A - State Transitions (Status is Open or Closed, no transitions necessary) |
N/A |
Planview Hub: All Tasktop Sync: 4.0 and later |
Any supported repository version: |
Comments
Supported Artifacts
Supported Work Items
Learn about the difference between containers and work items in Planview Hub here.
|
Supported Work Item Type |
Applicable Planview Hub Versions |
Applicable Repository Versions |
Unique URL? |
|---|---|---|---|
|
Issues |
Planview Hub: All Tasktop Sync: 4.9 and later |
Any supported repository version: |
Yes |
|
Milestones |
Planview Hub: 18.3 and later Tasktop Sync: 4.15 and later |
Any supported repository version: |
Yes |
Supported Containers
Learn more about containment in Planview Hub here.
|
Containers that can synchronize between repositories |
Applicable Planview Hub Versions |
Applicable Repository Versions |
Unique URL? |
|---|---|---|---|
|
N/A |
|||
|
Containers used to define the boundary of a collection |
|
|
|
|
Projects |
Planview Hub: All |
Any supported repository version: |
N/A |
|
Containers used for artifact routing |
|
|
|
|
Projects |
Planview Hub: All |
Any supported repository version: |
N/A |
Supported Field Types
Note: If one field of a given type is supported, others that are also that type in theory should also work. However, sometimes there are instances in which this is not the case due to the repository. So, while we can claim support for fields at the type level, there is a chance that some specific fields of a given type will not synchronize properly.
|
Standard Field Type |
Does Planview Hub support custom fields of this type? |
How is field type referenced in the repository? |
Sample Repository Fields Supported |
Particular Repository Fields NOT Supported |
|---|---|---|---|---|
|
|
|
|
Title Formatted ID Revision |
|
|
|
|
|
Milestone Repository State |
|
|
|
|
|
Labels |
|
|
|
|
|
|
|
|
|
|
|
Created at |
|
|
|
|
|
Updated at Closed at |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Issue Number |
|
|
|
|
|
Assignee Creator |
|
|
|
|
|
|
|
|
Learn how to configure relationships in Planview Hub here. |
N/A |
|
Milestone Issues (Read Only due to API limitation) |
|
|
|
|
|
Body |
|
|
|
|
|
|
|
|
|
|
|
|
|
Functional Limitations
|
Category |
Limitation |
Applicable Planview Hub Versions |
Applicable Repository Versions |
|---|---|---|---|
|
Configuration Requirement |
Labels Labels to be synced into GitHub must be defined on the GitHub repository. |
Planview Hub: All Tasktop Sync: 4.0 and later |
Any supported repository version: |
|
Third Party Functional Limitation |
Markdown Syntax The GitHub issues connector supports displaying and synchronizing of basic Markdown syntax. GitHub Flavored Markdown is not supported. That means strikethroughs, fenced code blocks, tables, and check boxes are not supported. Inline images will not be synced to or from GitHub, but the URLs pointing to the images will. Inline images in other repositories may be rendered inline on the Github repository if the image location is accessible to GitHub.com or your GitHub Enterprise server. Likewise, images originating in Github may render in the target repository if the repository supports inline images from external sources |
Planview Hub: All Tasktop Sync: 4.0 and later |
Any supported repository version: |