The concept behind the integration is the same as for the other issue trackers: the team discovers the product using a story map, schedules its possible deliveries into releases on the map, and pushes the implementable items to GitHub as issues.

Once cards are pushed to GitHub the following data can be synced:

In this guide, I assume that you already have a story map in StoriesOnBoard where you have admin access and a repo in GitHub where you also have admin privileges.

The connection between a story map and a GitHub repository can be set up from the … / Integration settings menu following the steps below:

1. Open the Issue tracker integration tab and select GitHub issues as the tool to integrate with

2. Create a personal access token for StoriesOnBoard in GitHub with repo scope.

StoriesOnBoard will access the GitHub repo with the user of this token, all the changes made in StoriesOnBoard will be synced to GitHub on behalf of this user.
Pro tip: if you’d like to be extra secure, you can create a technical user for StoriesOnBoard in GitHub and give it permission for only the necessary repos.

3. Copy the generated token to the StoriesOnBoard settings screen and click Connect

4. Select the GitHub repository and click on Link repository

Optionally set a label for exported issues: you can give a label for each issue that is created from the story map’s cards. This can be useful when you’d like to distinguish for example the newly scheduled issues for your team working in GitHub.

When a map is synced with GitHub, the cards’ statuses are taken from the issues’ statuses in GitHub and they are set by the status mapping rules on the story map.

The status mapping is easy by default as GitHub has only two statuses: Open and Closed

The mapping above means that when an issue is opened in GitHub, the corresponding card will be Todo on the map, and when it’s Closed in GitHub, it will be Done in StoriesOnBoard.

If you are using labels in GitHub to better differentiate statuses, you can map these as well using the label specifiers:

With the mappings above when an opened issue gets the label “in progress” it will be Doing on the map and when it gets the “to be discussed” it will become Todo again in StoriesOnBoard and so on…

We’ll see how the integration works with Waffle.io and the other systems later.

You can choose what fields to sync between GitHub and StoriesOnBoard by selecting them under the Synchronization options.

For the name and description changes, the sync is two-way, meaning that either when something is changed in StoriesOnBoard or in GitHub the changes will be reflected automatically and immediately on the other side. As both GitHub and StoriesOnBoard use Markdown for the description, they will be appearing the same at both places.

Releases are synced automatically with milestones only from StoriesOnBoard to GitHub (you can import them manually from the other way though).

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.

If you already have issues in GitHub that you’d like to put on the map, you can enable importing these. You can also enable manual importing of GitHub milestones into your map.

After all these sets, save the settings with the save button and you can start using your story map together with your GitHub repo.

You can push cards individually

or you can push all the cards in a release

Moving a card into another release:

will update the issue’s milestone in GitHub

If you had issues previously in GitHub or others are adding issues there and you’d like to see them in context on the map, you can import them from GitHub.

When there are issues to import, you’ll see the red arrow on the “Tool integration” icon:

The imported cards will be placed under “Cards imported from GitHub at …” blue card on the left side of the board:

You can move them afterward to their appropriate places on the map.

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 up the integration with GitHub as described above, push cards to GitHub and you’ll 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.

For easier setup you can use the provided default status mappings:

With the above setup if a card is dropped into the “In Progress” column in Waffle.io:

its status will change to “Doing” in StoriesOnBoard: