Setting up synchronization with GitHub

Learn more about how you can connect StoriesOnBaord to GitHub.

Tamás Párványik avatar
Written by Tamás Párványik
Updated over a week ago


StoriesOnBoard and GitHub integration overview

Integrating a story map with a GitHub repository allows teams to plan more effectively, utilizing the visual power of story mapping to achieve transparency and shared understanding among stakeholders. Bring the team around to the story map to see the big picture and take advantage of real-time and bidirectional sync with GitHub to keep everyone up to date at all time.

The integration makes it possible to plan releases on the story map and push cards to GitHub for execution. With the powerful integration between StoriesOnBoard and GitHub you can facilitate product discovery, define user journeys, put user stories into context and schedule releases to build and manage amazing products from the very beginning. This allows to do product discovery with user centric approach to build great products that users love.

Who can setup integration with GitHub

To be able to setup any integration with a story map you need to have an Admin user role on StoriesOnBoard. Additionally, you also need to hold Admin rights on GitHub as well to be able to make the necessary changes.

How to setup integration with GitHub

  1. Open the story map

  2. Go to “Integration settings“

  3. Select tool integration with ”GitHub issues”

  4. If you use GitHub Enterprise select that option and enter GitHub Enterprise server instance URL

  5. Generate access token on GitHub and enter on StoriesOnBoard

  6. Click on “Connect”

  7. Select a GitHub repository

  8. Click on “Link repository”

Step-by-step guide to link a story map to a GitHub repository

Open the story map you want to connect to aGitHub repository and select “Integration settings”.

Select GitHub as a tool to integrate with and enter your GitHub Personal access token. Then click to “Connect”.

💡 Tip - Learn more about How to generate your Personal access token on GitHub.

Setting up integration with GitHub 3.jpg

If you use GitHub Enterprise select that option and enter GitHub Enterprise server instance URL. Then click on “Connect”.

Setting up integration with GitHub 4.jpg

Now that you connected to GitHub, the next steps is to select the repository you want to link your story map. Then proceed with “Link repository”.

Setting up integration with GitHub 5.jpg

After selecting the right repository, you can adjust integration settings and then click on “Save”.

Setting up integration with GitHub 6.png

Integration settings for GitHub

Once you successfully connected to your GitHub repository, you will be able to access Integration Settings for GitHub as following:

Setting up integration with GitHub 1.jpg
GitHub integration settings.jpg

Label settings for exported issues

There is a possibility to distinguish those cards that were created in StoriesOnBoard when you export them to GitHub. This allows you to have a solid understanding about each newly scheduled issues coming from StoriesOnBoard helping the team who works in GitHub.

Status mapping with GitHub

When you link a story map to your GitHub repository, it is important to be clear about what is happening with your issues on both StoriesOnBoard and GitHub. By default GitHub offers only two statuses for issue management. An issue can be either Open or Closed.

Status mapping makes it possible to enhance your workflow and deliver more information for team members by using GitHub labels to indicate additional statuses for your issues. If you are using labels in GitHub to better differentiate statuses, you can map them to statuses in StoriesOnBoard by using the label specifiers:

💡 Tip - Learn more about How custom workflows work on StoriesOnBoard.

Setting up label for exported issues & Status mapping.jpg, HuBoard, ZenHub, integration

Integration with these tools is based on the GitHub integration as they are using GitHub’s database to display the issues. You just need to set the integration up with GitHub as described above, push cards to GitHub and you will get the cards in these GitHub connected tools.

Optionally status mappings can be fine-tuned for the ones that are using GitHub labels for storing the additional statuses.

Real-time synchronization with GitHub

Once the integration is established between StoriesOnBoard and GitHub, you can synchronize changes as following:

  • Synchronize name changes (issue title) bidirectionally

  • Synchronize issues’ description changes bidirectionally

  • Synchronize issue statuses from GitHub to StoriesOnBoard: when the issue’s statuses are updated in GitHub, the changes are reflected on the map according to the status mappings set in the map’s integration settings.

  • Synchronize release from StoriesOnBoard to GitHub as a milestone. We recommend managing releases/milestones in StoriesOnBoard as syncing is currently limited to one way from StoriesOnBoard to GitHub.

GitHub card sync settings.jpg

Release Synchronization with GitHub

Releases are synced automatically with milestones only from StoriesOnBoard to GitHub. If needed you can import them manually from the other way around as well.

Milestones will be created when a card is pushed with a release not existing in GitHub yet. Their names are synced when they are changed in StoriesOnBoard.

💡 Tip - Learn more about Release synchronization with GitHub.

GitHub release synch setting.jpg

Import setting

You can enable editors to import new cards from GitHub (only non closed issues will be imported).

Import settings GutHub.jpg

Learn more about:

Did this answer your question?