GitHub integration – What’s new in StoriesOnBoard – October 2016

We are pleased to announce the next release of StoriesOnBoard with, HuBoard, ZenHub, and GitHub integration and simple formatting options in cards’ title.

GitHub integration

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

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

  • Issues 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.
  • Card’s title to the issue’s title both ways
  • Card’s description to the issue’s description both ways
  • Card’s release from StoriesOnBoard to GitHub as milestone. We recommend managing releases/milestones in StoriesOnBoard as syncing is currently limited to one way from StoriesOnBoard to GitHub.

Setting up the GitHub integration

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 … / Board settings menu following the steps below:

Connect to a GitHub repository

  1. Open the Issue tracker integration tab and select GitHub issues as the tool to integrate with
    GitHub integration - StoriesOnBoard
  2. Create a personal access token for StoriesOnBoard in GitHub with repo scope.
    GitHub integration - StoriesOnBoard
    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 StoriesOnBoard settings screen and click Connect
    GitHub integration - StoriesOnBoard
  4. Select the GitHub repository and click on Link repository
    GitHub integration - StoriesOnBoard

Label for exported issues

GitHub integration – StoriesOnBoard

Optionally set a label for exported issues: you can give a label for each issues that are 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.

Status mappings

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

GitHub integration - StoriesOnBoard

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:

GitHub integration - StoriesOnBoard

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 and the other systems later.

GitHub integration – sync options

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

GitHub integration - StoriesOnBoard

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 uses 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.

Import options

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.

GitHub integration - StoriesOnBoard

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

Working with a connected GitHub repo

Push new cards to GitHub

You can push cards individually

GitHub integration - StoriesOnBoard

or you can push all the cards in a release

GitHub integration - StoriesOnBoard

Move cards between releases

Moving a card into another release

GitHub integration - StoriesOnBoard

will update the issue’s milestone in GitHub

GitHub integration - StoriesOnBoard

Import issues from 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:

GitHub integration - StoriesOnBoard

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

GitHub integration - StoriesOnBoard

You can move them afterward to their appropriate places on the map., HuBoard, ZenHub, integration

Integration with these tools are 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:

GitHub integration - StoriesOnBoard

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

GitHub integration - StoriesOnBoard

it’s status will change to “Doing” in StoriesOnBoard:

GitHub integration - StoriesOnBoard

Simple formatting options in cards’ titles

Previously you could use some HTML tags to format titles and descriptions. Unfortunately, sometimes this prevented adding greater-than and less-than symbols into these texts and occasionally these were conflicting with our anti-XSS filters added because of security reasons.

Now using the HTML tags to format texts are disallowed in both the title and the description fields. In the description, you can use Markdown as before and in the title, you can use the following formatting options:

GitHub integration - StoriesOnBoard

Please note that when formatted titles are edited in the connected integrated systems (including GitHub), the formatting will be lost as these systems don’t have support for formatting in titles.

As always any feedback is greatly appreciated. Please use our feedback widget at the bottom right corner of the application if you need help setting up the integration or have any other question about StoriesOnBoard.

Previous announcement:

Release announcement of April 2016

How useful was this post?

Click on a star to rate it!

Average rating 0 / 5. Vote count: 0

No votes so far! Be the first to rate this post.

We are sorry that this post was not useful for you!

Let us improve this post!

Tell us how we can improve this post?