Disclaimer: The integration described below is obsolete and we would recommend using the new one instead.
Abilities:
There are 6 integration options between Kanbanize and GitHub. Here they are:
1. You can "Track commits." Each commit will show as a comment to a card in Kanbanize
2. You can "Track Github project issues." When a new issue is created in GitHub, this will create a card in Kanbanize, and when an issue is closed, the card will be moved to "Done."
Note: that this integration requires that you have selected "Project Issues Board" in the URL set up (more on this to follow)
3. You can "Update card details" when there is a new commit.
4. You can "Move card" when there is a new commit.
5. You can "Update card status" - this allows you to block/unblock a card or change the block reason when there is a new commit.
6. You can "Log time to card" when there is a new commit.
The integration is in one direction only – from GitHub to Kanbanize.
For example: when an issue is closed, the corresponding Kanbanize card is moved to "Done", but moving a card to Done will not get the issue closed.
Setup:
Kanbanize Configuration:
1. In Kanbanize, go to Administration -> Integrations -> GitHub -> Configuration
2. Click Configure to setup and copy the URL to use in GitHub.
3. IMPORTANT: Make sure the *Kanbanize User selected for the integration has access to the boards where it's expected to track commits or issues!
4. The "Project Issues Board" is only required if the you plan to have issues mapped between GitHub and Kanbanize
5. The "Only Last Commit" is used if you plan to add old commit changes to the card. We suggest you keep this as by default set to "true".
GitHub Configuration:
1. Go to your GitHub project page -> Settings -> Webhooks -> Add webhook
2. Set up the Webhook:
URL – paste the URL generated in Step 2
Content-type: application/json
Triggers:
Pushes – If enabled, all branches and all commits of the project are inspected for Kanbanize card IDs.
Issues and Issue comments – If enabled, GitHub project issues will be tracked in a Kanbanize board.
Check only if the "Project Issues Board" URL parameters is set!
And you are good to go! From now on, every commit message will be processed with the Kanbanize service, and your changes will be reflected on the corresponding Kanban card. When a local branch is pushed to a repository, all local commits will also be processed one by one.
Note: If you do not want to "Track Github project issues", select "Just the push event." for "Which events would you like to trigger this webhook?" in GitHub settings. If you also want to track issues, you will have to select "Issues" to trigger the event.
Usage:
The integration can update Kanbanize cards through "#" hashtag commands in the message.
Track commits
#taskid / #id – this is a required parameter for the integration to work. 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)
Examples of commit messages:
- Change in the logging module. #id 1234
- Change in the logging module. #taskid 1234
Note: This is required for all push options.
Track GitHub project issues
Important: "Project Issues Board" is required if you want a new Github issue to create a card in Kanbanize, or to move the card to 'Done' when an issue is closed. For all other options, the board is not required and can be left as "Not set"
Upon configuration as per the requirements, when an issue is created, a new Kanbanize card will be created. Each issue update will be reflected on the card.
Mapping:
GitHub issue <-> Kanbanize card
Title <-> Title
Description <-> Description
Assignee <-> Assignee
Labels <-> Tags (if a tag matches an available card type in the Issue tracking board in Kanbanize, the type will be set to the card accordingly)
Note: GitHub allows Closing issues via commit messages - if issue tracking is enabled and your commit message is related to a GitHub issue, you don’t have to provide a task id parameter.
Update card details
#title, #description, #priority, #assignee (with alias @<username>), #color, #size, #tags, #deadline, #extlink, #type
All these parameters can be changed via the commit message using our API functions.
Examples of commit messages:
- Change in the logging module. #taskid 1234 #priority high #color ffaaff #deadline 2014-12-12 @Peter
- #taskid 1234 Change in the logging module. @Peter
Note: If your text includes multiple words separated by space, put it in double-quotes. For example, if you want to update "title" and change it to "New Title", you have to set it like this: #title "New Title." If you do not add quotes around the text, it will use only the first word
Move a card
#column, #lane, #boardid, #position, #exceedingreason (if you are to exceed the WIP limit, provide a reason with this parameter)
Examples of commit messages:
- #taskid 1234 #column "In Progress" - move the card to the "In Progress" column
- #taskid 1234 #column Done #boardid 12 #position 1 - move the card to the "Done" column to the board with id 12
- #taskid 1234 #column “Done.Ready for Deployment” #lane bugs #boardid 12 #position 1 - move the card to the "Ready for Deployment" column to the board with id 12. The card will be placed in top position in the "Bugs" swimlane.
We also support the following move shortcuts:
#move “Ready for testing/Platform Team” – Move the task to the “Ready for testing” column and the “Platform Team” swimlane
#move Development/ – Move the task to the Development column
#move “/Platform Team” – Move the task to the Platform Team swimlane
#requested – Move a task to the first column in the Requested section
#inprogress – Move a task to the first column in the In Progress section
#done – Move a task to the first column in the Done section
#<section> first – Move a task to the first column in the section
#<section> 2 – Move a task to the second column in the section
#<section> last – Move a task to the last column in the section
<section> can be any of the following: requested, inprogress, done
Update card status
#block, #editblock, #unblock
Examples of commit messages:
- #taskid 1234 #block “Not enough resources.”
- #taskid 1234 #editblock “Still not enough resources.”
- #taskid 1234 #unblock
Log time to card
#loggedtime – The number of hours you want to log to the task.
Examples of commit messages:
- #taskid 1234 #loggedtime 2
- #taskid 1234 #loggedtime 0.5
If you have any issues setting up the integration, just reach out to our support team!