GitHub Integration

While GitHub provides teams with a medium for creating content rich collaborative repositories of work, it can be hard for teams to get the high-level picture of your projects & issues. To better visualize your GitHub repos in a consumable, simple to understand roadmap, users can create a one-way connection with GitHub which allows them to pull content into their roadmaps and visualize it against other projects across all the tools your team uses on a daily basis.

Getting Started with GitHub

Linking Roadmunk to your GitHub Instance

In order to connect your Roadmaps to your instances & repos in GitHub, an Account Admin on your Roadmunk account will need to establish the connection between Roadmunk and GitHub first. Once this connection is established, users will be able to view and select this integration option during their on-roadmap setup and save both instance & credential details for future setup of additional roadmaps.

Create a New GitHub Integration

To create a new GitHub integration in Roadmunk:

Click into your avatar in the bottom-left and navigate into the Account Settings menu.
Once in Account Settings, navigate to the Integrations tab along the top.
Select the + Add an integration button and choose GitHub from the configuration menu.
In the setup window that appears, enter the following details:
- GitHub Integration Name: The reference name which describes to yourself and your team the GitHub instance you're connecting to.
- GitHub Integration URL is shown but cannot be edited due to the static nature of this pathway. Unlike other Roadmunk integrations, the instance being accessed is defined at the roadmap level, not the account level.
Once these details have been entered, click the Create Integration button to finalize the setup.

Update an Existing GitHub Integration

To update an existing GitHub integration in Roadmunk:

Click into your avatar in the bottom-left and navigate into the Account Settings menu.
Once in Account Settings, navigate to the Integrations tab along the top.
Select the Edit button in the GitHub Integration you're looking to update.
In the edit window that appears, the administrator who created the integration can update:
- GitHub Integration Name: The reference name which describes to yourself and your team the GitHub instance you're connecting to.
Once these details have been changed, click the Update Integration button to finalize the setup. Changes are applied immediately for all users across the account.

Remove an Existing GitHub Integration

To delete an existing GitHub integration in Roadmunk:

Prior to deletion, ensure that no roadmaps are currently using this particular integration.
Click into your avatar in the bottom-left and navigate into the Account Settings menu.
Once in Account Settings, navigate to the Integrations tab along the top.
Select the Delete button in the GitHub integration you're looking to remove.
Once selected, the integration will be deleted immediately and will be removed from the menu.

Generating Credentials for Roadmunk in GitHub

In order to authorize the data transfer between Roadmunk and GitHub and ensure that user permissions are respected, Roadmunk relies on a user-generated credential which allows the user to view and pull their data from their projects & boards. In this case, we require a Personal Access Token (PAT) generated in GitHub as your credential and during the roadmap setup will allow you to set a Credential Label so you can easily differentiate this particular token from others you may use (in the case of teams working across multiple active GitHub deployments).

Users can generate a Personal Access Token from the Settings menu in GitHub and reference GitHub's article on creating a personal access token for more details. In order to create a token, users must first specify both the Token Expiration and Token Scope. The teams at Roadmunk and GitHub strongly recommend that you set an expiration date for your token to help keep your information secure. Once they've expired (or as needed prior to expiration), tokens can be revoked, removed, or regenerated from the Personal Access Tokens menu. When choosing the Token Scope, Roadmunk requires that you select the repo option from the provided menu - this allows Roadmunk to properly access and view all repos and their associated content.

Permissions Limitations between Roadmunk & GitHub

Please note that Roadmunk will respect the permissions of your GitHub account tied to the user-provided credentials mentioned above and will limit content visibility during the sync setup to match that of GitHub. This means that if your provided credentials only allow you to view certain content, then these limitations will carry over into Roadmunk.

If you do find that you are unable to access or view certain repos, projects or issues are not populating, please connect with your GitHub administrator to ensure that you have the appropriate permissions to view and access that particular content.

Connecting your Roadmaps to GitHub

Integrations Setup Walkthrough

It's a quick and easy process to set up an integration between your GitHub repos and your team's roadmaps in Roadmunk. The setup process can be broken down into three stages: triggering the integration, applying synchronization settings, and applying field and filter settings. Once those have been completed, your roadmap will be set to pull and visualize data from GitHub as needed.

Step 1 - Triggering the Roadmap Integration

Once the integration connector has been set up by your Account Admin, you will be able to select the Setup GitHub Integration option in the Integrations tool on your roadmap. Triggering this integration will not overwrite your existing data; however, once you've linked a roadmap to a project you are unable to remove that connection or change the specified repo.

This option will activate a setup wizard which will walk you through the process of connecting your roadmap to a specific repo in GitHub to act as a data source for your roadmap.

Step 2 - Applying Synchronization Settings

Once in the setup wizard, you will be prompted to follow the preset workflow to complete the integration. In the first phase of this workflow, you will have the option to select which GitHub connector you would like to pull project data through, the synchronization direction (one-way, at this time), and the automatic sync cadence (default is set to 12 hours).

Step 3 - Applying Credentials, Field & Filter Settings

Once your instance has been selected, you'll be prompted to choose your credentials for syncing with GitHub. If you haven't previously set up credentials to sync with, please enter the Personal Access Token that was generated in the steps above and apply a Credential Label for future reference.

After these details above have been provided, you will be able to select the repo you would like to pull data from and the state of issues being pulled to bring in only the relevant content is being pulled. Once these settings have been applied, you'll be able to specify Start Date & End Date and select the GitHub fields to use on your roadmap. While the specified repo can't be changed after the setup, the user-defined dates and fields can be updated later if needed.

Once you've completed this phase of the setup, you'll be taken to a confirmation screen to let you know that the integration has been setup successfully. After completing the setup wizard, you'll be returned to the roadmap view where your data will begin to populate from your specified GitHub repo.

What to Expect After Integrating

Once you've integrated your data from GitHub, there will be a few changes to your roadmaps. The following changes may occur after you've setup your integration:

All fields pulled from GitHub are Account-Level by default - Since the properties and values of these synchronized fields are managed in GitHub, we automatically promote them to account-level so they can be accessible as common fields in Portfolio roadmaps.
There is an External ID field that appears in the Items Table view - When synchronizing data from GitHub, we pull in the ID of each issue for reference on your roadmap. This is clickable and linked out to your team's GitHub instance, so you can quickly access the respective work item from either your Table view and Item Card.
Unable to change or add new projects on a single roadmap - As with our other integrations, we limit connections between roadmaps and third-party tools to be a 1:1 connection. This means that you will be unable to sync multiple projects into a single roadmap; however, you will be able to create multiple roadmaps for each project and use those as sources in a Portfolio roadmap.
Additional Date fields will be read-only - Due to a variance in field formatting between Roadmunk and GitHub, any additional Date fields selected which are not mapped to Start and End Dates will be pulled in as read-only text fields.
Tokens may expire a set number of days after being created - Unlike API tokens generated for credentials in Jira, which have a longer-term expiry, Personal Access Tokens generated in GitHub will expire depending on your specifications during the setup. These tokens can be easily regenerated for continued use, but your in-app credentials will need to be updated.

Modifying GitHub Integration Setup

Once the initial integration setup is complete, the roadmap owner will be able to modify the setup at any time. To do so, from the Items Table or in a roadmap visualization, simply click the GitHub button (which replaced the Integrations button) in the roadmapping toolbar and select "Modify Setup" from the drop-down menu. This will open the integration setup menu and you can update sync settings, credentials, filter work items, and select fields.