Businessmap Integration with GitLab (bi-directional)

1. Introduction

This article describes the integration between Businessmap (https://businessmap.io/) and GitLab (https://gitlab.com).

A potential reader of this article is expected to be familiar with Businessmap (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 Businessmap Support team at support@businessmap.io

 

2. Integration Capabilities

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

From Businessmap to GitLab:

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

2. Create a MR (merge request) on a Businessmap event (e.g. a card moved to a specific column)

From GitLab to Businessmap:

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 Businessmap 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 Businessmap 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 Businessmap board.

 

3. Prerequisites

To use the integration, you need the following:

In Businessmap:

• 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)

In GitLab:

• Configure the GitLab-Businessmap link (done only once at the beginning of the usage)

 

4. Initial Configurations in Businessmap

API Credentials

To use the integration, you would require a Businessmap 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 set up and use a dedicated user with its API key for the integration. 

Mandatory custom field

The integration requires one mandatory Custom Field in Businessmap, where the GitLab full repository name is stored for each card integrated with GitLab. It could be a text or dropdown 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 Businessmap, utilizing the Businessmap 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 field 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 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:

• 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 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 is 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 Businessmap board.
• Base branch – The main branch that will be used by the Businessmap to GitLab integration to determine which branch to copy to create a new one, when a card is created in Businessmap.
• 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 – Dropdown field containing a list of card types configured for the specific board in Businessmap.
• 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 Businessmap 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 Businessmap 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 Businessmap 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 Businessmap 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 Businessmap 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 Businessmap 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 Businessmap as your Product development life cycle (PDLC) solution, where you have a 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 Businessmap to GitLab

Here is what an example workflow can look like in Businessmap:

1. On a Businessmap event (e.g., a card moved to a specific column) create a Branch in GitLab

To create a branch on a Businessmap event, we create a card in Businessmap 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 branch 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 Businessmap.

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

 

From GitLab to Businessmap:

3. Create a card from a GitLab commit.

To inform the integration that you want to do something in Businessmap, 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 Businessmap, 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 Businessmap, 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 Businessmap 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 Businessmap, 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.

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 Businessmap board.

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.