18. March, 2019

Switching to Zenhub

By Lars Kruse

Switching to Zenhub

Waffle.io is shutting down, we’re moving to ZenHub. Zenhub has the advantage that’s is a GitHub extension, so from a usability point of view it’s much better integrated in the user interface.

Get Started

  1. Install the Browser extension for ZenHub (Availabel for Chrome and Firefox).
  2. Browse to one of your repositories (e.g prolike/prolike.io#zenhub)
  3. Autorize the ZenHub app for both public and private repos.

First time use

Quite similar to Waffle.io

  1. Create a workspace name - This is actually an improvement to Waffle.io where one repo would be the top-level and the others would be dragged in. In ZenHub they are not parent-child relations but rather siblings in a joint workspace.
  2. Add a description - Also an extra feature compared to Waffle.io
  3. Connect repos - pull in the ones that belongs to the workspace

Define the columns

ZenHub referes to the columns in the Kanban as pipelines. The predefined pipelines are

New issues -> Icebox -> Backlog -> In progress -> Review/QA -> Done -> Closed.

Of all these, Closed is the only one that is required (default available). The rationale behind this flow is described here at ZenHub’s help page.

In Waffle.io the card’s journey through the columns was defined by labels. ZenHub uses it’s own internally maintained metadata. So to model the Phlow in ZenHub you don’t need to define any labels, just simply rearrange and rename the columns (pipelines) to read.

New issues -> Backlog -> Up next -> To do -> In progress -> Closed

The New issues pipeline was not part of the line up in Waffle.io, but it’s definitely an improvement, it makes the project’s in box is visible, so we’ll keep it and embrace it.


ZenHub doesn’t define it’s own priorities, so we will just continue to use our own labels for this.

Estimates - T-shirt sizes becomes story points

ZenHub has it’s own built-in approach to estimates, it’s based on complexity or story points and takes offset in the fibbonachi numbers 1 - 2 -3 - 5 - 8 -13 -21 and then ends with 40.

Waffle.io also had it’s own internally implemented estimates, but we chose not to use them, because the we’ren’t availabel outside the context of Waffle.io. In ZenHub it’s acceptable since we can actually access this data on an API and we even have access to a few CLI tools zhb, zencli and maybe the most promising zenhub-cli which means that we can incoporate this in our automated Phlow.

And since ZenHub is not hosted on it’s own URL like Waffle.io was, but instead it’s made availabel through an extension of the GUI on GitHub it feels intuitive. We’ll go with this.

We will translate the new complextity to ideal-working-hours. (E.g. how “long time would it take, if we gave the issue to a developer who had all the necessary competences, and could work the issue without interruptions until done”).

So essentially we will stop using our own T-shirt size labels and use the built in story points instead, translating the semantics as follows:

Small: 1-2 story points. Medium: 3-5 story points. Large: 8 story points. Too large: 13 or higher.

Briefings becomes Epcis

ZenHub has built in support for Epics, which essentially are Container issues. It seems to work quite well, and comepletely replases our need for “Briefings”.

Dependencies, release, reporting etc

There are actually a few more features such as blocking dependencies and modelling releases that seems useful, and ZenHub also encourages the use of Milestones, since they play a central role in the quite useful predefined reports. We can examine this further down the process…

Bulk upgrades (MANUAL work ahead!)

We could probably build a small too to make the transition from Waffle.io to ZenHub here’s the MANUAL process I’ve been using for the few projects I’ve migrated so far. It starts, after you have defined the workspace collection and the pipelines…

Before we start… a word on selction and bulk actions: You can click one of the issues on the icon of the assignee, this will enter into selection mode, click on any other issue to add to selections. While in selection mode, an array of bulk actions becomes available as push buttons over the board. Do Your Thing.

The process is really a repetition over almost the same cycle:

Pipelines (columns)

  • Use a filter to see the issues with status - * one at a time
  • Select all the issues and do a bulk action to move the to the corresponding pipeline, or simply drag them there one by one.
  • Clear the filter and start over

Consider deleting the status labels previously used in the Phlow - to force yourself out of Waffle today - rather than in two months.


  • Use a filter to see the issues with size - * one at a time
  • Select all the issues and do a bulk action to set the corresponding story point estimate.
  • Clear the filter and start over

Move all from “New Issues” to “Backlog”

Since the use of New Issues is new to us, but default to ZenHub, we need to move all issues from New Issues to Backlog


  • Use a filter to see the issues with briefing one at a time
  • In the right menu select the Epic item and then convert to Epic
  • Make a note of each isses that is mentioned throughoput the log of the Briefing issues and for each of them
    • Open the issue
    • Use the Epic menu item to add the individuial issue to the epic.

Rest In Peace Waffle


Sign up to our Profeed and receive news and information about our latest events, or if you can't wait, sign up for our event right away!

Profeed Events