Kanbanize Integration with GitHub (bi-directional)

 

1. Introduction

This article describes the integration between Kanbanize (https://kanbanize.com/) and GitHub (https://github.com/).

A potential reader of this article is expected to be familiar with Kanbanize (boards, cards, business rules, etc.) and GitHub (branches, pull requests, etc.).

However, if you have any questions or encounter some difficulties along the way, do not hesitate to contact the Kanbanize Support team at support@kanbanize.com.

2. Integration Capabilities

The integration is bi-directional. It offers the following capabilities:

From Kanbanize to GitHub

1. Create a new branch in a GitHub Repo on a Kanbanize event (e.g. a card moved to a column)

2. Create a Pull Request (PR) on a Kanbanize event (e.g. a card moved to a some other column)

From GitHub to Kanbanize

3. Create a card from a GitHub commit message.

4. Link a branch to a card in Kanbanize on a GitHub commit.

5. Add comments to the a card, when:

• new comment is added to a commit or pull request in GitHub.
• branch is renamed or deleted in GitHub.
• pull request state is changed (i.e. it is opened or closed) in GitHub.

6. On rejected pull request (like closed but not merged), the related card will be blocked (if this is configured), and a rework card will be created as a predecessor of the original card.

7. On finished pull request (closed and merged), the related card in Kanbanize will be moved to the previously configured column.

Additional features

8. Several boards can be linked to one repository.

9. Several repositories can be linked to one Kanbanize board.

 

3. Prerequisites

To use the integration, you need the following:

Kanbanize

• Add custom fields of type text, to the boards that will be integrated:
  - "reponame" (custom field) is mandatory. 
  - "Branch name" and "Pull Request" custom fields are optional. 
  
  Note: The names of the fields could be as you like, the integration will ask explicitly which ones to be used and will map them accordingly. 
  
  
• Available business rules (configuration is done only once at the beginning of the usage)

GitHub

• Install a GitHub Kanbanize Integration App provided by us. 
• Configure the GitHub-Kanbanize link (done only once at the beginning of the usage)

 

4. Initial Configurations in Kanbanize

API Credentials

To use the integration, you would require a Kanbanize API Key of a user with the Account Owner role.

You can retrieve your API key by navigating to the My Account menu (top right corner) and switching to the API tab. We suggest that you setup and use a dedicated user with it's API key for the integration. 

Mandatory custom field

The integration require one "reponame" mandatory Custom Field in Kanbanize, where the GitHub full repository name is stored for each card integrated with GitHub. It could be a text or drop down custom field with values in the GitHub URL-style format: GroupName/RepositoryName. 

Note: Please do not add any spaces in the values. Auto space removal will be improved in the next version.

Every card (bug, feature, etc.) created manually in Kanbanize, utilizing the Kanbanize to GitHub integration, must have a custom field set with the full repository name value. Otherwise, the integration will not know where to create a branch or pull request (PR).

The custom filed name could be as you like, but we will be referring to it as “Reponame CF” further in this article. In the image below you see Git Branch, Git PR and reponame as custom field names. 

Tip: It could be a good idea to add the CF with a preset value to a card template. For example, 1 template per project with a repository name and other project-specific properties predefined in the the card. 

If you select those templates upon card creation or set a default template on your board, you will never forget to set the repository name again.

 

Optional custom fields

A link or text custom field where the URL for the branch that was created will be stored. 
This CF is not obligatory, but if you add it to your board, it will provide a single-click connection between a card and its related branch.

We will be referring to this CF as “Branch CF” further in this article.

A link or text custom field where the URL for the created pull request will be stored. 
This CF is not obligatory, but if you add it to your board, it will provide a single-click connection between a card and its related pull request.

We will be referring to this CF as “PR CF” further in this article.

More on the types of custom fields and how to create and manage them can be found in the following two articles:

• Types of Custom Fields
• How to Create and Manage Custom Fields?

Business Rules

Furthermore, two business rules will be created automatically during the configuration process. One business rule is necessary for branch creation, and the other is needed for pull request creation. At a later stage, you can fine-tune the business rules that were created automatically.

Please check our dedicated section on Business Rules for more details.

 

5. Configurations in GitHub

You need to install the integration from this URL:

https://github.com/apps/kanbanize-gh-integration

If the app is not installed yet, you will see that button:

Otherwise, you will see the configuration button:

Click it and select the repositories you want to integrate.

After the repository configuration, you will be redirected to the integration's main application page located at: https://github.integrations.kanbanize.com/

 

6. Configuring the Integration

1. Access the integration’s main application page at: https://github.integrations.kanbanize.com

Note: If you add the integration to a repository, GitHub will redirect you to that URL automatically as the last step.

Log in to GitHub and authorize OAuth2 authentication:

 

2. Fill in the login fields and enter the configurations for your domain:

Note: The integration needs a full URL as a Kanbanize domain value. For example: “https://company.kanbanize.com” is correct, “company” only is NOT correct.

3. Edit any of the existing configurations or "Create new link" providing the required information. Setting repository and business rules only available during the creation/setup of a new integration link! 
Note: In order to edit existing configurations or add new ones the user needs to have owner or admin permissions to the GitHub repository.

 

You need to specify the following values:

• Repository – The repository name that you want to link to a Kanbanize board.
• Base branch – The main branch that will be used by Kanbanize to GitHub integration to define which branch to copy from, and use to create a new one, when a card is created in Kanbanize.
• Target board for the repository – The board where the cards will be created.
• Save branch link in custom field – The name of the “Branch CF” custom field where the link to a branch will be populated when a card creation is linked to a branch via commit.
• Save PR link in custom field – To specify the name of the “Pull Request CF” custom field where the link to the pull request will be populated when a card is linked to it.
• Target column for cards of merged PRs – The column where cards will be moved to when pull requests are completed.
• Target column for new reworks – The column where rework cards will be created.
• Card type for rework – Drop down field containing a list of card types configured for the specific board in Kanbanize.
• Rework prefix – Custom prefix to be added to card title when a rework card is created.
• Target column for new cards – Column where new cards will be created when a card creation is triggered by a GitHub commit.
• Block configuration – To specify whether a card should be blocked and the block reason when a pull request is rejected.
• Create business rules toggle – If enabled, this toggle will create the business rules required for the Kanbanize to GitHub integration which creates new branches or pull requests in GitHub upon card creation. After selecting the toggle, the following popup will be displayed:

 

 

You need to specify the following values:

• Create branch business rule target column – The column to be used to trigger the creation of a branch in GitHub, when a Kanbanize card is moved to it.
• Create PR business rule target column – The column to be used to trigger the creation of a pull request in GitHub, when a Kanbanize card is moved to it.
• Custom field with the full repository name – The name of the “Reponame CF” custom field where the repository name will be populated. This is the repository where branches and pull requests will be created.

After setting the options, the business rules will be created when clicking on the submit of the form.

Later you can change these values in the Kanbanize business rules admin section.

Note: The default configurations are:

• For branches name will {{cardType}}/{{cardId}}-{{cardTitle}}.
• For PR’s title will be “REVIEW {{cardTitle}}” and its body “PR opened from Kanbanize”.

If you have properly setup cardTypes and cardTitles, you will have names like:
- Customer Issue/33234-Missing Settings Buttons on Mac Safari Browser
- Feature/33243-New extended API methods for history data

Business Rules Authorization Token

For communication from Kanbanize to GitLab a Business Rules Authorization Token is used.

If you create the business rules through the integration app, the Business Rules Authorization Token will be added automatically.
However, if you want to create a business rule manually, you will need to generate the token.
You can do it by pressing the special link:

Note: Only one Business Rules Authorization Token per Kanbanize account can exist.

If you regenerate the token, all business rules that point to the GitLab Integration App will stop working and you will have to update their tokens to reactivate them.

Note: For security reasons, you can see the Business Rules Authorization Token only once in the app. Make sure you keep it in a safe place. Of course, if you lose it or forget it you can always regenerate it and update your business rules.

 

7. Use Cases

In this section, we will explore the use cases described in Integration Capabilities section. At this point, it is assumed that the setup of the integration from the previous sections has been completed and your integration is ready to run.

The main scenario is that you use Kanbanize as your Product development life cycle (PDLC) solution, where you have Kanban board workflow with multiple columns such as "Development", "Review", "QA Testing", "Deployment", etc ... 

On the other hand you have the GitHub as your source code control system and you link the commits and automate your branching and pull requests with your day to day tracking of work items, such as Bug, Features, Improvements and Product Releases. 

 

A scenario from Kanbanize to GitHub

1. Create a branch on a Kanbanize event (e.g., a card moved to a specific column)

To create a branch on a Kanbanize event, we create a card in Kanbanize with the repository name (format must be owner/repository) in the “Reponame CF” custom field.
We then move the card to the column configured in the business rule to create a new branch.

If everything is OK, you will see the “Git Branch” custom field populated with a new value.

Note: If you have created the Branch name and PR custom field as a Link-type custom field, you will be able to go to the new branch with 1 click on the custom field in Kanbanize.

Now, if someone makes a new commit, we will see the first comment in the Comments tab of the card.

Note: If you click a link in the comments, you will be forwarded to the correspondent branch, commit, or PR.

2. Create a pull request on a Kanbanize event (e.h., a card moved to a specific column)

Following from the previous scenario, when development is finished, we can move the card to trigger the “PR Create” business rule.

When development is finished, we can move the card to trigger the 'PR create' business rule.

If everything is OK, you will see the “Git PR” custom field populated with a new value too.

 

 

 

From GitHub to Kanbanize

3. Create a card from a GitHub commit.

To inform the integration that you want to do something in Kanbanize, you have to start a commit message line with any uppercase/lowercase combination of //knbz or //Kanbanize. 

For example, the following combinations are valid:  //knbz, //Kanbanize, //KNBZ, //KANBANIZE, //kanbanize, etc. 

For the sake of simplicity, we will use only //knbz from now on in this article, but feel free to use any other valid command start.

To create a new card in Kanbanize, just add the following message to your commit: 

//knbz new  

a new card will be created in all linked boards.

Note: you can add a command in both: the header and the body of the commit message 

 

4. Link a branch to an existing card in Kanbanize on a GitHub commit.

To link an existing card in Kanbanize just add the following message to you commit: 

//knbz your_card_id  

Note: replace your_card_id with a real card id in your account. E.g. 23783 

If 23783 is correct ID of the card you have access to, the card with ID: 23783 will be linked to the branch where commit is done. If you have several boards in different Kanbanize accounts, linked to the same repository then you would need to use the following command: 

//knbz 23782 mykanbanizeaccount 

The card with ID: 23783 in the account called “mykanbanizeaccount” will be linked to the branch where commit is done. As an alternative you can use the following syntax:

//knbz 23782 1 

where 1 is an index of the board link based on creation time.  

For example: if you have linked a repository called myrepository with a board A in a KanbanizeAccountBar at the beginning and later linked the same repository with a board B in a KanbanizeAccountFoo, the command //knbz 23782 1 will try to link the branch with KanbanizeAccountBar and //knbz 23782 2 will try to link the branch with KanbanizeAccountFoo 

 

5. Add comments to a linked card when a new comment is added to a commit or pull request, a branch is renamed or deleted or a pull request state is change (i.e. it is opened or closed) in GitHub.

To add comments to a card, the card will need to be linked to a GitHub branch or pull request. This can be done using use cases 1, 2, 3 or 4 above.

Following on from the abovementioned use cases, any comments added to a commit or a pull request will be automatically added to all cards linked to that branch or pull request.

The same will be applied, if the branch is renamed or deleted or a pull request state is change

6. On rejected pull request (closed but not merged), the related card will be blocked (if configured), and a rework card will be created as a predecessor of the original card.

To block a related card and create a rework card on rejected pull request, the card will need to be linked to a pull request as described in use case 2. This functionality will only work if the block card has been configured previously on the integrations main page as described in section 5.

If the reviewer of code in GitHub is unhappy with the new development, the pull request can be closed without merging.

In this case, the card is blocked, a comment is added, and the rework card is created as it is set in the configuration.

 

7. On finished pull request (closed and merged), the related card will be moved to the previously configured column.

To move a related card on finished pull request, the card will need to be linked to a GitHub pull request as described in use case 2.

If the reviewer of code in GitHub is happy with the new development, the pull request can be closed.

 

In this case, the card is unblocked automatically and moved to the Done column.

 

 

Additionally, following on from use case 6, as soon as the rework is finished and the rework card has been closed in Kanbanize, the reviewer can reopen the pull request and close it correctly with a corresponding merge:

 

In this case, the card and the rework card are unblocked automatically and moved to the Done column.

Additional features

8. Several boards can be linked to one repository.

In order to link several boards to one repository, the setup process will need to be performed as described in section 5, configuring the Integration for each board. Just set the same board name for each repository link.

9. Several repositories can be linked to one Kanbanize board.

In order to link several repositories to one board, the setup process will need to be performed as described in section 5, configuring the Integration for each repository. Just set the same repository name for each board link.

8. Special Cases

Renaming the repository

What happens if someone changes a repository name or the name of the owner/organization?

If the app has received at least one event (commit, etc.) between configuration creation and name change, then the configuration will be updated automatically. Otherwise, if no event has been received, the user will have to create a new configuration manually.

 

9. FAQ

Q: I want to customize a PR title or description. How to do it?

A: You can change the respective business rules in order to customize those.

Q: I want to use the same board/workspace for non-Github-related cards, and I receive an error every time that type of card enters the “Branch” column. How to avoid it?

A: You can add additional filters/conditions to the business rules configuration.