How to Link an Existing GitHub Issue with a BoldDesk Ticket
GitHub is a cloud-based platform that helps developers store, manage, track, and collaborate on software projects using Git, a version control system. Think of GitHub as a central workspace where development teams can:
- Store source code
- Track bugs and feature requests
- Review code changes
- Collaborate with team members
- Manage software releases
- Maintain project documentation
The GitHub integration enables support and engineering teams to collaborate more effectively by linking GitHub issues directly to BoldDesk tickets. Once linked, comments and updates can be synchronized between both platforms, helping teams stay aligned and reducing manual effort.
Prerequisites
Before linking a GitHub issue, ensure that:
- The BoldDesk GitHub App is installed and configured. Explore How to Install and Configure the GitHub Integration.
- The GitHub organization and repository have been authorized.
- You have access to the target GitHub repository.
- The GitHub integration is enabled in your BoldDesk account.
Link an Existing GitHub Issue
To link an existing GitHub issue to a BoldDesk ticket:
- Open the required ticket in BoldDesk.
- Locate GitHub app within the ticket apps.
- From the dropdown, click Link Issue.
- Search for the GitHub issue using available filters:
- Repository - a repository is a GitHub project that contains your source code, files, issue tracker, and development history. When the GitHub integration is configured in BoldDesk, administrators grant access to one or more GitHub repositories. Agents can then create or link issues only from those authorized repositories. Only authorized repositories appear in the dropdown.
- Search Issue - This only activates once the repository is selected. You can input and search by issue ID or title. Only issues that match the selected repository will be listed for the search.
- Select the desired GitHub issue from the search results.
- Click Link. Please check the workflow image and visual below for more insights.
After the issue is linked, BoldDesk creates a ticket-to-issue association and immediately enables synchronization. You can create and link issues from BoldDesk as well. Explore How to Create and Link a GitHub Issue with a BoldDesk Ticket.
Verify the Linked Issue
When a GitHub issue is linked to a BoldDesk ticket, the GitHub widget displays key information about the associated issue.
| Field | Description |
|---|---|
| Issue | The GitHub issue number associated with the ticket. This is the unique identifier used within the repository to track the issue. |
| Unlink | Removes the association between the BoldDesk ticket and the GitHub issue. This does not delete or modify the issue in GitHub. Synchronization stops once the issue is unlinked. |
| Repository | The GitHub repository where the issue resides. A repository is a GitHub project containing source code, files, documentation, issues, and development history. Example: helpdeskintegration/helpdesk. |
| Title | The title or summary of the GitHub issue. This typically describes the bug, feature request, or task being tracked. |
| State | The current status of the GitHub issue. Common values include Open and Closed. This helps agents quickly identify whether the issue is still being worked on or has been completed. |
| Labels | Categories assigned to the issue in GitHub for organization and filtering. Examples include bug, enhancement, feature, or task. If no labels are assigned, the field displays --. |
| Assignee | The GitHub user currently responsible for working on the issue. If no user has been assigned, the field displays Unassigned. |
| Milestone | The GitHub milestone associated with the issue. Milestones are used to group issues into releases, sprints, or project phases. If no milestone has been assigned, the field displays No milestone. |
| Open in GitHub | Opens the linked issue directly in GitHub, allowing agents to view additional details, comments, assignees, labels, milestones, and development activity. |
Once a GitHub issue is linked to a BoldDesk ticket, synchronization begins automatically based on the configured integration settings. Depending on your configuration, ticket notes, status updates, priority changes, and GitHub comments may be synchronized between BoldDesk and GitHub. This allows agents to easily track the associated development work without leaving the ticket.
Synchronization After Linking
Synchronization begins automatically when a GitHub issue is linked to a BoldDesk ticket.
BoldDesk → GitHub
The following ticket activities are synchronized to the linked GitHub issue as comments:
- Ticket notes
- Status updates
- Priority updates
Ticket replies are excluded and not added in the GitHub issue as comments.
GitHub → BoldDesk
The following GitHub activity is synchronized to the linked BoldDesk ticket:
- New issue comments
GitHub comments are added to the ticket as private notes, allowing support agents to stay updated on engineering discussions.
Ticket replies are intentionally excluded from GitHub synchronization and are not added as comments to the linked GitHub issue. This helps keep GitHub issues focused on engineering-related discussions and prevents customer-facing communication from being shared automatically. If information from a customer reply needs to be shared with the development team, add it as a Ticket Note in the linked BoldDesk ticket. The note will then be synchronized to the associated GitHub issue as a comment.
Unlink a GitHub Issue
To remove the association:
- Open the linked ticket.
- Navigate to the GitHub app within the ticket apps.
- Click Unlink.
What Happens When an Issue Is Unlinked?
The association between the ticket and GitHub issue is removed.
- Synchronization stops immediately.
- The GitHub issue remains unchanged.
- No GitHub data is deleted.
Troubleshooting
If you are unable to locate or link a GitHub issue:
- Verify that the GitHub App has been installed successfully.
- Confirm that the repository is authorized and configured.
- Ensure you have access to the repository.
- Verify that the issue exists and matches the selected search criteria.
- Contact your administrator if repository permissions were recently modified.
Frequently Asked Questions
-
Can I search for issues across multiple repositories?
Yes. You can search issues within repositories that are accessible through the configured GitHub installation. -
Will synchronization start automatically after linking?
Yes. Two-way synchronization begins immediately after a GitHub issue is successfully linked. -
What information is synchronized?
The integration synchronizes:- Ticket notes to GitHub comments
- Ticket status updates to GitHub comments
- Ticket priority updates to GitHub comments
- GitHub issue comments to BoldDesk private notes
-
How are duplicate comments prevented?
The integration tracks synchronized records and uses loop-prevention mechanisms to ensure the same comment is not synchronized multiple times. -
How are conflicting updates handled?
The integration follows a Last Updated Wins strategy when handling synchronization conflicts.
