4 Comments

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

GitHub issues 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 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
     01_select_github_as_tool_to_integrate_with
  2. Create a personal access token for StoriesOnBoard in GitHub with repo scope.
    02_github_new_personal_access_token
    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
     03_copy_access_token_to_storiesonboard
  4. Select the GitHub repository and click on Link repository
    04_select_repository

Label for exported issues

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.
05_label_for_exported_issues

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

 06_status_mappings_defaul_github

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:

 07_status_mappings_labels

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.

Sync options

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

 08_sync_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 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.

 09_import_options

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

 10_push_card_to_github

or you can push all the cards in a release

 11_push_cards_from_release

Move cards between releases

Moving a card into another release

 12_drag_into_another_release_storiesonboard

will update the issue’s milestone in GitHub

 13_drag_into_another_release_github

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:

15_import

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

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

Waffle.io, HuBoard, ZenHub, Overv.io 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:

 17_waffleio_status_mappings

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

 18_waffleio_status_change

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

 19_waffleio_status_change_in_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:

20_title_formatting_options

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.



Comments

Comment by Keji

Is this a one to one relationship similarly the JIRA integration? Or can you link multiple Github issues?

Keji
Comment by Arpi

Hi Keji,

It is one to one, you can link one card to one GitHub issue. Can you write an example when you'd need to link to multiple GitHub issues? You can also write it in the feedback widget if you don't want to share it publicly.

Thanks,

Comment by Michael Torres

I keep getting the error "Cannot create webhook: The error was: Object reference not set to instance of an object" whenever I try to save my issue tracker integration details (using the GitHub integration). Wondering what I'm doing wrong? The error message is not very helpful

Michael Torres
Comment by Arpi

Hi Torres,
I'm sorry for the late reply and getting this error. Thanks for contacting us using the widget since then. Just for the record here: we think we've found the cause of the problem and deployed a fix. Please try how it works now.

Thanks,

Post comment