This is a bi-directional integration between GitHub and Kanbanize and it provides a basic synchronization of GitHub Issues to Kanbanize Cards and vice-versa. There are several scenarios where this integration provides additional value:
Multiple Teams: when you have multiple teams working in Kanbanize and/or in GitHub and you need to bridge them. For example, Team A, Tram B, and Team C are working in GitHub and Team K is working in Kanbanize and receives requests/tasks in the form of issues opened in GitHub.
As the rest of the teams are used with GitHub they report issues in the Team K repository in GitHub and they also expect to receive comments and updates in GitHub, while Team K uses the Kanban Method advantages and a complex workflow setup in Kanbanize.
Product Development / Project Management: Using related boards and implementing the Kanban Portfolio breakdown setup facilitate the Product and Project Managers in Kanbanize to monitor the overall work progress at different levels. Once the tasks are broken down for the teams to be executed, they are requested into their systems (GitHub Repositories) for execution.
Using GitHub as Source Control System only and the Workflow is Kanbanize: In this scenario all the development flow is implemented in Kanbanize with detailed states like Planned, Requested, Technical Design, Development, Code Review, Testing, etc., while the commit and source changes have to be related to a Kanban Card for traceability purposes.
Note: We do not support nor recommend scenarios where the team is expected to be able to work equally between the two systems. Like, half of the team is using only GitHub and the other members are using only Kanbanize. As the systems compliment/enhance each other, there is no possibility for full replication, that's why only basic information is kept in sync to support the scenarios above.
- Bi-Directional Sync of GitHub issues and Kanbanize cards using Webhooks.
- Create Issue / Kanbanize Card
- Update Issue / Update Card Details
- Close Issue / Move Card to Done
- Commit Change / Add Card Comment
Note: Depending on the setup the integration could be one or bi-directional. For example, when an issue is closed, the corresponding Kanbanize card is moved to "Done", but moving a card to Done might not be required to closed the issue in GitHub.
1. In Kanbanize, go to Administration -> Integrations -> GitHub -> Configuration
Note: This might take a couple of seconds as the system is installing and preparing an integration module dedicated just for your account instance.
Hint: Through the integration setup, you might be required to make some modification to your Kanbanize Account and GitHub Projects, so read this first to the end, so you know up-front what needs to be prepared and then start with the setup.
2. GitHub Integration Login Credentials.
If you need only one-way integration from GitHub to Kanbanize you can skip this step.
For security reasons you will be required to provide a set of login parameters:
I) Client ID & Client Secret:
These are OAuth Login parameters provided by GitHub and to obtain them you need to register an GitHub OAuth App with access to the repositories want to integrate. To Create such App and grand access follow these steps:
- Go to your GitHub Account Settings (Top Right Avatar Icon)
- From the Developer Settings tab, create a new OAuth App
- For Homepage URL and Authorization callback URL add the following URL:
- Register your application and copy the Client ID and Secret that will be shown to you.
II) After applying the Client ID and Secret from Step I, you'll be redirected to GitHub and asked to authenticate with a user, that will be used from Kanbanize to perform modifications in your GitHub repositories.
Note: For security and better traceability purposes, we propose to create and use a new/dedicated integration user. Once setup, enter its username and password.
3. GitHub WebHook Registration
The integration provides a unique webhook URL for your account. Use this URL to register it to all your Repositories, you want to integrate. Copy the URL to use in the Webhook registration setup:
- Go to your GitHub Repository page -> Settings -> Webhooks -> Add webhook
- At the Payload URL field, paste the URL link for your account.
- From the Trigger Events options, either select:
- Send me everything, or
- Select Individual Events: (issues and issue comments)
- Use the JSON Format for sending the payload data!
4. Optional WebHook Parameters
WebHook URL could look like this:
** column and lane names are case sensitive, use %20 if you have spaces in the names.
*** if the card has been moved to another board the update/sync from GitHub to Kanbanize will stop as the integration will not be able to locate the card.
5. Kanbanize Integration User
Select a user, which credentials will be used to make modifications on behalf of the GitHub system. We advise to register a dedicated user, just for that purpose, as this is better for traceability and proper functioning of the integration.
Note: If you use your own user for example as the integration one, a modification made by you in Kanbanize will not be reflected in GitHub as the system will treat this as an anti-loop mechanism and will prevent this changes from happening.
6. Select the Kanbanize Boards
From the Kanbanize side, you will be required to select a set of boards that would be mapped to your GitHub Repositories.
Note: If you don't see the boards you want to integrate, make sure the user is invited to those boards.
Important: The integration works 1:1 (Repository : Kanbanize Board) for as many Repositories and Boards as you've selected to integrate. In order to have this mapping, it is very important to have your Kanbanize Boards named exactly (Case Sensitive) as your GitHub Project Repositories.
Note: As per the GitHub restriction repository names (i.e. relatively Kanbanize Boards) should not have spaces into their names. For example "My Test Project" board should be "My-Test-Project" as this will be forced from GitHub.
7. GitHub Integration Username
Type the exact username, already used in the authorization that is used to make modifications in GitHub on behalf of Kanbanize changes. We advise registering a dedicated user, just for that purpose, as this is better for traceability and proper functioning of the integration.
This user name is used as an anti-loop mechanism to prevent duplicated changes.
8. GitHub Owner
Type the exact Owner (name of the GitHub account). For example second part of your URL to GitHub
Create / Update
Upon configuration as per the requirements above, when an issue is created, a new Kanbanize card will be created. Each issue update will be reflected on the cards as follows:
GitHub issue <-> Kanbanize card
Title <-> Title
Description <-> Description
Assignee <-> Assignee (names have to match, only one assignee is supported in Kanbanize)
Labels <-> Tags
Note: New Issues/Kanbanize Cards are created in the backlog of the board matching the repository name. To get them created into another column/swimlane, just create a business rule for that particular board to move the card once it's been created.
Comments are added from both sides by the integration users. The user name of the person making the comment is added in front of the comment itself, for example:
Comment by KBintegration:
john: Hey we need more info here?
Note: Markup language is not supported and the text in the comment and the description of the Task/Issue is converted to plain text format.
Close / Move
- From GitHub to Kanbanize:
When an Issue is closed in GitHub, the integration system will try to move the corresponding Kanbanize Card in a column named "Done".
Note: Make sure when you design and configure your board, to keep one column (sub-column in the lowest level) named exactly "Done", where closed issues will be moved.
- From Kanbanize to GitHub:
When a Kanbanize Card is moved to a column that contains the "Done" word or some of its parent columns contains "Done" the corresponding GitHub Issue will be marked as closed. For example, you could create a board with the following done area structure:
| Done |
| OK | Failed | Rejected | Done |
- This way you could add extra "Done" statuses and not just a "Close" state to your Kanbanize Cards / GitHub issues.
Upon commits in your GitHub Repositories we support the following:
#taskid / #id – this is a required parameter inside the title/description of the commit mesasge, so we could link the change in GitHub to the corresponding Kanbanize card. You can provide it in one of these three formats:
- #id 1234 (can be anywhere in the commit message and takes priority if present)
- #taskid 1234 (can be anywhere in the commit message and takes priority if present)
- 1234 (must always be the first thing in your commit message)
Examples of commit messages:
- `Change in the logging module. #id 1234`
- `Change in the logging module. #taskid 1234`
- `1234 Change in the logging module.`