5 Steps for Integrating GitHub with Your Roadmap Tool

Why Connect GitHub to Your Roadmap?

A product roadmap is a blueprint that communicates your team’s strategic plans and goals for the product. Your development team’s day-to-day progress will inform how you maintain and update the strategic items on the roadmap. But those task-level details should not live in the roadmap itself.

The roadmap should always remain a high-level, visually clean display of the strategic components of your team’s priorities and progress. If you add every task, the roadmap will become cluttered and lose value as an at-a-glance strategic reference point to keep the team aligned on your big-picture plans.

But this poses a challenge.

If you keep your roadmap and the details of your cross-functional team’s progress completely separate, how can your roadmap always reflect the most current picture of each strategic item’s status? It can’t. With a standalone roadmap—for example, one you build as a spreadsheet or presentation file—you will need to manually update the document each time your team makes progress on any initiative on the roadmap. If you don’t make these updates frequently, the roadmap will always simply display a given initiative as in-progress until you mark it complete.

One way to solve this challenge is to use a web-based roadmap app—specifically one that integrates with your team’s other workflow applications, such as GitHub. This will allow you to sync your development team’s work on the product with your roadmap while leaving the roadmap’s primary display clean and high level.

If visitors to the web-based roadmap want to see the current development status of an epic or feature, they can simply click into that item and bring up an up-to-date chart listing that item’s percentage of completion.

Here are a few reasons this can be an invaluable addition to your roadmap, and your product development efforts in general.

3 Benefits of Integrating Your Roadmap and GitHub

1. It saves time and reduces the need for meetings.

In a traditional organization, the product and development teams meet to discuss the planned work on the product, and then the developers go off and begin working in a silo. The only way for the product managers to stay updated on the product’s progress is to have meetings with the development team’s representatives.

By integrating development’s progress tracking in GitHub directly with the roadmap itself, the product team can receive an up-to-date status report of the developers’ progress on their work.

2. It helps keep the cross-functional team aligned.

Another benefit of connecting developments’ GitHub updates to the roadmap is that it helps the product team communicate the product’s status to other stakeholders across the company.

With an up-to-date picture of how far a feature is in development, a product manager can more accurately estimate for the sales and marketing teams when to expect that feature to be ready for release.

3. It helps you set and adjust stakeholder expectations.

A roadmap’s strategic plan can never be perfect or guaranteed to play out exactly as written. It is based only on the best available information the product team has at the time. Realities often change within an organization. A competitor’s successful market launch, for example, might force a company to change priorities suddenly, pulling resources away from the product they were working on and leaving several initiatives on that product’s roadmap delayed.

This is another reason linking your team’s GitHub account to the roadmap can be beneficial. Imagine a company’s senior management decides to delay work on your team’s product and divert development resources onto another project. Your team will have a better chance of earning stakeholder approval to complete development work on an essential feature. If you can show those execs, the development team is already 88% finished with their work.

5 Steps to Integrate Your Roadmap Tool with GitHub

Step 1: Choose the right roadmapping tool

Assuming you’re already using GitHub for your development and version-control tracking, you’ll want to find a roadmap tool that integrates easily with your GitHub account. A few key integrations feature to look for include the ability to:

  • Link multiple GitHub issues with a single epic or theme in the roadmap app. Many individual GitHub items should roll up to a single strategic initiative on the roadmap. You’ll want to link them to all this initiative, to create an overall percentage completion.
  • Sync your GitHub updates automatically, every day, or to make more frequent updates manually if you choose.
  • Search for specific GitHub items within the roadmap app, so you can quickly find out whether a given task is complete or not—without having to access your company’s GitHub account.

Bottom line: Look for a roadmap app that allows your team to move back and forth quickly and easily between your product roadmap and GitHub.

Step 2: Find the right level of detail to sync.

Not every GitHub issue will directly affect a specific epic, theme, or another strategic initiative on the roadmap. The development team might use its GitHub platform to track internal ideas, for example, or even to collect user feedback that the team can review later.

On the other hand, some of the GitHub your development team creates might affect several of your roadmap initiatives simultaneously. To gain an accurate picture of the percent complete of those initiatives, you’ll want to link these GitHub items to more than one roadmap initiative simultaneously.

So you will want to spend some time with your development team, figuring out how they’re breaking up their work into tasks and other items.

Step 3: Import relevant GitHub issues into your roadmap

Now it’s time to begin pulling in the issues and tasks your development team has created in GitHub into your product roadmap app.

If you’ve selected the ProductPlan GitHub integration, you can do this easily and in just a few minutes. We’ve written a short page to walk you through how to link roadmap initiatives with GitHub issues.

Step 4: Prioritize your initiatives

Assuming you’ve created a series of strategic themes and epics for your new product, you need to decide on priorities. In what order will you ask your development team to begin tackling your strategic initiatives? No matter how large your organization, you will be able to secure only limited development resources to your project. So you will need some type of criteria to determine which items you’ll want your developers to work on first.

If you’ve chosen a roadmap app that includes built-in prioritization, you can perform this step there. ProductPlan’s Parking Lot feature, for example, lets you add your list of epics and features and then perform a cost-benefit analysis of each, using a consistent scoring approach.

You can create a side-by-side comparison of each initiative on your list according to metrics such as:

  • Market share potential
  • Revenue potential
  • Customer delight
  • Strategic value
  • Effort vs. cost

See how easily you can weigh competing roadmap items in the ProductPlan Parking Lot

When you and your team have assigned scores to all initiatives, according to all of the chosen categories, you’ll know which epics and other items to work on first.

Step 5: Build your roadmap.

Now that you’ve decided which epics and other items to prioritize, you can begin adding those details to your product roadmap.

Once you’ve built the basic framework of your roadmap—themes, epics, features, and rough timeframes, for each—you can begin pulling in GitHub issues that roll up to each of these initiatives. (Remember, some items in GitHub might affect the progress of more than one roadmap initiative, so you’ll want to assign those issues to all relevant initiatives.)

New to roadmapping? Get some best practices in our free book: A Beginner’s Guide to Product Roadmaps

You can organize your roadmap’s contents according to dates or date ranges. You can also group themes, epics, and other items by swim lanes. With a purpose-built roadmap app like the one available from ProductPlan, you can add, remove, and rearrange the details and view of your roadmap with just a few clicks.

And even more important for our discussion here: You can sync your ProductPlan roadmap directly with your issues in GitHub.

Ready to connect GitHub and your roadmap?

Start with your ProductPlan free trial >>