Businessmap Integration with GitHub (bi-directional)

 

1. Introduction

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

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

2. Integration Capabilities

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

From Businessmap to GitHub

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

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

From GitHub to Businessmap

3. Create a card from a GitHub commit message.

4. Link a branch to a card in Businessmap 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 Bsuinessmap 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.

 

Important

The Businessmap integration with GitHub performs the following operations:

• Retrieves a list of repositories and checks current user permissions.
• Fetches repository branch information (only names and IDs).
• Creates new branches.
• Creates new pull requests.

Additionally, the Businessmap integration listens for webhooks sent by GitHub to update the Businessmap board state. For example, if a commit is made, a new comment is added to a card.

Please note that Businessmap integration does not access repository files.

 

3. Prerequisites

To use the integration, you need the following:

Businessmap

• 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 Businessmap Integration App provided by us. 
• Configure the GitHub-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 "reponame" mandatory Custom Field in Businessmap, 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 Businessmap, utilizing the Businessmap 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 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 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 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/businessmap-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 Businessmap 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 is only available during the creation/setup of a new integration link! 
Note: 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 Businessmap board.
• Base branch – The main branch that will be used by Businessmap to GitHub integration to define which branch to copy from, and use 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 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 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 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 Businessmap 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 Businessmap 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 Businessmap 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 Businessmap 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 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.

 

7. Use Cases

In this section, we’ll explore use cases that illustrate the integration capabilities discussed earlier. We’ll assume that your integration setup is complete and ready to go.

A common scenario is using Businessmap as your product development life cycle (PDLC) solution, with workflows that include columns like "Development," "Review," "QA Testing," "Deployment," and more.

Alongside Businessmap, you use GitHub as your source code control system, linking commits and automating branching and pull requests to track work items like bugs, features, improvements, and product releases.

Essentially, this integration keeps your code development process in GitHub in sync with your Businessmap workflow, moving together in parallel.

 

A scenario from Businessmap to GitHub

This is what your Businessmap workflow may look like:

• Start Column: When items move to the “Start” column, a new branch is created.
• Development Column: When cards are in the “Development” column, commits are made.
• Review Column: Moving items to “Review” generates a pull request.
• On Production Column (Done): Once the pull request is completed in GitHub, the card advances to the “On Production” column in Done.

Here is how to recreate a similar scenario:

 

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

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.
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: Make sure that the "Git Branch" and "Git PR" custom fields are set to "link" type so you can open them with a single click directly from 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 PR.

2. Create a pull request on a Businessmap 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 Businessmap

3. Create a card from a GitHub 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.

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 Businessmap on a GitHub commit.

To link an existing card in Businessmap 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 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 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 Businessmap, 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.

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.

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.