Important: There is a new GitLab Integration available, and we highly recommend that you use it going forward. You can learn more about it in the dedicated article. However, we continue to support the old version for existing integrations.
Abilities:
1. Track commits as comments in a corresponding Businessmap card. (Only commit and push events are tracked.)
2. Track GitLab project issues as cards in a Businessmap board
3. Update card details
4. Update card status
5. Log time to card
The integration is in one direction only – from GitLab to Businessmap.
For example, when an issue is closed, the corresponding Businessmap card is moved to Done but moving a card to Done in Businessmap will not get the issue closed in GitLab.
Setup:
1. In Businessmap, go to Administration -> Integrations -> GitLab -> Configuration
2. Enable the integration and setup and copy the URL to use in GitLab.
3. Go to your GitLab project page -> Settings
4. Click on Integrations.
5. Set up a Webhook:
URL – paste the URL generated in Step 2
Trigger:
Push events – If enabled, all branches and all commits of the project are inspected for Businessmap card IDs.
Comments and Issues events – If enabled, GitLab project issues will be tracked in a Businessmap board.
An additional URL parameter is required – issuesboardid – The ID of the board that must keep the project issue cards.
And you are good to go! From now on, every commit message will be processed in Businessmap and your changes will be reflected on the corresponding Businessmap card. When a local branch is pushed to a repository all local commits will also be processed one by one.
Important: There is a known problem of missing payload data, that is needed for the integration to work, when testing with an example request. It is recommended to test the integration out with a 'real' test issue for this reason.
Usage:
The integration can update Kanbаnize 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)
- 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.`
Track GitLab project issues
Upon configuration as per the requirements, when an issue is created a new Businessmap card will be created. Each issue update will be reflected on the card.
Mapping:
| GitLab | Businessmap | ||||
| GitLab issue | <-> | Businessmap card | |||
| Title | <-> | Title | |||
| Description | <-> | Description | |||
| Weight | <-> | Size | |||
| Due date | <-> | Deadline | |||
| Assignee | <-> | Assignee | |||
| Labels | <-> | Tags * |
* If a tag matches an available card type in the Issue tracking board in Businessmap, the type will be set to the card accordingly
Note: GitLab allows Automatic issue closing - if issue tracking is enabled and your commit message is related to a GitLab 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`
- `1234 Change in the logging module. @Peter`
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:
- `1234 #column "In Progress"` - move the card to the "In Progress" column
- `1234 #column Done #boardid 12 #position 1` - move the card to the "Done" column to the board with id 12
- `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 a bunch of move shortcuts that make it all easier
#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, progress, done
Update card status
#block, #editblock, #unblock
Examples of commit messages:
- 1234 #block “Not enough resources.”
- 1234 #editblock “Still not enough resources.”
- 1234 #unblock
Log time to card
#loggedtime – The number of hours you want to log to the task.
Examples of commit messages:
- `1234 #loggedtime 2`
- `1234 #loggedtime 0.5`