Top

Articles in this section

See more

Kanbanize Integration with GitHub

Avatar
Kanbanize Help
  • Updated

Index:
1. Introduction
2. What to Expect from this Integration
3. Requirements
  -Kanbanize
4. Initial Configurations
  -GitHub
  -Kanbanize
5. Configure the Integration Page
6. Creating Business Rules Automatically
   -Business Rules Authorization Token
7. Integration Capabilities
8. How to Use the Integration
  -GitHub
  -Kanbanize
9. Special Cases
  -Renaming the repository
10. FAQ

 

1. Introduction

This article describes the integration between Kanbanize (https://kanbanize.com/) and GitHub (https://github.com/), created by Kanbanize in 2022.

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. What to expect from this integration

Let’s start with a small example of how this integration works.

  • We create a card in Kanbanize.

1.png

Img. 1

Note: It's important to set a custom field with the repository name (the format must be owner/repository).

  • We move the card to the column configured in the business rule to create a new branch.

2.png

Img. 2


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.

3.png

Img. 3

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

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

4.png

Img. 4

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

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

5.png

Img. 5

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

6.png

Img. 6

7.png

Img. 7

As soon as the rework is finished, the reviewer can reopen the PR and close it correctly with a corresponding merge:

8.png

Img. 8

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

 

9.png

Img. 9

 

3. Requirements

What do you need to start using GitHub Kanbanize integration:

- Kanbanize

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.

Additionally, you will need several custom fields created and added to the board:

Obligatory custom field:

  • Custom field to store the GitHub full repository name. It could be a text or dropdown custom field with values in the GitHub URL-style format: OwnerName/RepositoryName.
    Please do not add any spaces in the values.
    We will be referring to this CF as “Reponame CF” further in this article.

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?

Also, during the configuration, you will be asked about other details related to your Kanbanize instance, needed for the normal functioning of the integration (e.g., column names for branch and PR creation, card type for rework cards, blockers, etc.).

 

4. Initial Configurations

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

12.png

Img. 10

Otherwise, you will see the configuration button:

13.png

Img. 11


Click it and select the repositories you want to integrate.

14.png

Img. 12

After the repository configuration, you will be redirected to the integration's main application page located at:

https://github.integrations.kanbanize.com/login 


-Kanbanize

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 PR 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:

https://knowledgebase.kanbanize.com/hc/en-us/sections/115001149249-Business-Rules- 


5. Configure the Integration Page

1. Access the URL:

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:

new_1.png

new_2.png

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

new_3.png

Img. 13

 

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. This will be improved in the next version.

3. Edit any of the existing configurations or add a new one providing the required information (repository and business rules only available during the creation):

new_4.png

Img. 14

6. Creating Business Rules Automatically


You can create Kanbanize business rules automatically from here:

new_5.png

Img. 15

After selecting the switch, the following popup will be displayed:

18.png

Img. 16


You need to specify the following values:

  • Destination column for branch creation. When a card with the custom field from the 3rd dropdown is moved into that column, the business rule will create a branch in GitHub.
  • Destination column for PR creation. When a card with the custom field from the 3rd dropdown is moved into that column, the business rule will create a PR in GitHub.
  • Custom field name where full repository name (in the owner/reponame format) will be set in every card.

For example, if we have the following setup, as shown in the next image:

  • When a card is moved to “In Progress”, development starts, and we need a branch to be created.
  • When a card is moved to “Review”, development is finished, and we need a PR to be created.
  • We keep the repository name in the custom field called “reponame”.

19.png
Img. 17 - Example board configuration

Then the result of the configuration will look like this:

20.png

Img. 18

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:

- By default, the created branch will be {{cardType}}/{{cardId}}-{{cardTitle}}.
- By default, the PR’s title will be “REVIEW {{cardTitle}}” and its body “PR opened from Kanbanize”.


-Business Rules Authorization Token


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

new_6.png

Img. 19

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 this button:

new_7.png

Img. 20

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

If you regenerate the token, all business rules that point to the GitHub 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. Integration Capabilities

The integration offers the following capabilities:

  • Create a branch on a Kanbanize event (e.g., a card moved to a specific column)
  • Create a PR (pull request) on a Kanbanize event (e.g., a card moved to a specific column)
  • Add comments to the card on:
    -commits, branch renames, or deletions
    -PR comments and state changes (open or close)
  • On rejected PR (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.
  • On finished PR (closed and merged), the related card will be moved to the previously configured column.


8. How to Use the Integration

To use the integration, you need the following:

-GitHub

  • Installed app into the repository (done only once at the beginning of the usage)
  • Configure the GitHub-Kanbanize link (done only once at the beginning of the usage)

-Kanbanize

  • Configure business rules (done only once at the beginning of the usage).
  • Add custom fields to the board. Reponame CF is mandatory; Branch name and PR custom fields are recommended.
    Every card (bug, feature, etc.) 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). You can use text or dropdown-type custom fields.
    Note: The Full repository name value must have a standard Github URL-style format: OwnerName/RepositoryName. Please do not add any spaces in the value. No leading, no trailing, no in-between spaces. Auto space removal will be improved in the next version.

21.png

Img. 21 - Don’t forget to set the full repository name value, or it will not work :-)

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.

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.

 

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

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

 

 

Related articles