1. Introduction
This article describes the integration between Kanbanize (https://kanbanize.com) and GitLab (https://gitlab.com).
A potential reader of this article is expected to be familiar with Kanbanize (boards, cards, business rules, etc.) and GitLab (branches, merge 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 GitLab:
1. Create a branch on a Kanbanize event (e.g. a card moved to a specific column)
2. Create a MR (merge request) on a Kanbanize event (e.g. a card moved to a specific column)
From GitLab to Kanbanize:
3. Create a card from a GitLab commit message.
4. Link an existing card from a GitLab commit message.
5. Add comments to the card on:
- commits, branch renames, or deletions
- MR comments and state changes (open or close)
6. On rejected MR (closed but not merged), the corresponding card in Kanbanize will be blocked (if configured), and a rework card will be created as a predecessor of the original card.
7. On finished MR (closed and merged), the corresponding 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:
A "Reponame" (custom field) is mandatory;
"Branch name" and "Merge 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. - Available business rules (configuration is done only once at the beginning of the usage)
GitLab
- Configure the GitLab-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 mandatory Custom Field in Kanbanize, where the GitLab full repository name is stored for each card integrated with GitLab. It could be a text or drop down custom field with values in the GitLab 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 GitLab 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 merge request (MR).
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 MR 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 merge 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 merge request.
We will be referring to this CF as “MR 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:
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 MR 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. Configuring the Integration
1. Access the integration’s main application page at: https://gitlab.integrations.kanbanize.com
Log in to GitLab 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.
Note: Setting repository and business rules only available during the creation/setup of a new integration link!
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 the Kanbanize to GitLab integration to determine which branch to copy 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 MR link in custom field – To specify the name of the “MR CF” custom field where the link to a MR will be populated when a card is linked to a MR.
- Target column for cards of merged MRs – The column where cards will be moved to when MRs 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 GitLab commit.
- Block configuration – To specify whether a card should be blocked and the block reason when a MR is rejected.
- Create business rules toggle – If enabled, this toggle will create the business rules required for the Kanbanize to GitLab integration which creates new branches or MRs in GitLab upon card creation. After selecting the toggle, the following popup will be displayed:
In it, 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 GitLab, when a Kanbanize card is created in it.
- Create MR business rule target column – The column to be used to trigger the creation of a MR in GitLab, when a Kanbanize card is created in 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 MRs 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 MR’s title will be “REVIEW {{cardTitle}}” and its body “MR 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.
6. Use Cases
In this section, we will explore the use cases described in Integration Capabilities sections. 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 use case 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 GitLab as your source code control system and you link the commits and automate your branching and merge requests with your day to day tracking of work items, such as Bug, Features, Improvements and Product Releases.
The scenario from Kanbanize to GitLab:
1. On a Kanbanize event (e.g., a card moved to a specific column) create a Branch in GitLab
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 as step one.
We then move the card to the column configured in the business rule to create a new branch.
If everything is OK, the brach will be created in GitLab and you will see the "Branch CF" custom field populated with a new value, pointing to the Branch.
Note: If you have created the “Branch CF” 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 MR.
2. Another Kanbanize event (e.g., a card moved to a specific column), then create a Merge Request in GitLab.
Following from the previous scenario, when development is finished, we can move the card to trigger the “MR Create” business rule.
If everything is OK, you will see the “MR CF” custom field populated with a new value too and the corresponding Merge Request in your GitLab repo.
Note: If you have created the "MR CF" custom field as a Link-type custom field, you will be able to go to the GitLab MR with 1 click on the custom field in Kanbanize.
From GitLab to Kanbanize:
3. Create a card from a GitLab 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.
4. Link an existing card from a GitLab commit.
To link an existing card in Kanbanize, you can use the same method as the one for creating a new card, just add the card id to the commit, instead of "new" as shown below:
//knbz your_card_id
Note: replace your_card_id with a real card id in your account. E.g. 23783
If 23783 is a correct ID of a card you have access to, the card with ID 23783 will be linked to the branch where the 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 the 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 KanbanizeAccauntBar at the beginning and later linked the same repository with a board B in a KanbanizeAccauntFoo, the command //knbz 23782 1 will try to link the branch with KanbanizeAccauntBar and //knbz 23782 2 will try to link the branch with KanbanizeAccauntFoo.
5. Add comments to a card on commits, branch renames, or deletions and MR comments and state changes (open or close).
To add comments to a card, the card will need to be linked to a GitLab branch or MR. This can be done using use cases 1,2,3 or 4 above.
6. On rejected MR (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 MR, the card will need to be linked to a MR 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 GitLab is unhappy with the new development, the MR can be closed without merging.
In this case, the card is blocked, a comment is added, and the rework is created as it is set in the configuration.
<--->
7. On finished MR (closed and merged), the related card will be moved to the previously configured column.
To move a related card on finished MR, the card will need to be linked to a GitLab MR as described in use case 2.
If the reviewer of code in GitLab is happy with the new development, the MR can be closed.
In this case, the card is automatically 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 MR 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
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.
7. Special Cases and Settings
1. 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.
2. What if I want to customize a MR title or description. How to do it?
You can change the respective business rules in order to customize those.
3. I want to use the same board/workspace for non-GitLab-related cards, and I receive an error every time that type of card enters the “Branch” column.
You can add additional filters/conditions to the business rules configuration.