Contents:
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
Open the story map
Go to “Integration settings“
Select tool integration with ”GitHub issues”
If you use GitHub Enterprise select that option and enter GitHub Enterprise server instance URL
Generate access token on GitHub and enter on StoriesOnBoard
Click on “Connect”
Select a GitHub repository
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.
If you use GitHub Enterprise select that option and enter GitHub Enterprise server instance URL. Then click on “Connect”.
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”.
After selecting the right repository, you can adjust integration settings and then click on “Save”.
Integration settings for GitHub
Once you successfully connected to your GitHub repository, you will be able to access Integration Settings for GitHub as following:
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.
Waffle.io, HuBoard, ZenHub, Overv.io 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.
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.
Import setting
You can enable editors to import new cards from GitHub (only non closed issues will be imported).
Learn more about: