Bitbucket-Trello-Hook

Bitbucket POST web hooks handler for Trello written in PHP. This is a small web application written using the beautiful SLIM framework and it uses the Trello API. For more information about webhooks you can read the Bitbucket docs.

Example

Close task commit hook:

$ git commit -m 'Fixes very bad bug #aBc123XyZ' 

This will move the card #aBc123XyZ to the "Done" list and add a comment with a link to the commit.

These are the keywords to use if you want to move task:

Default Action Keywords
close
closes
closed
closing
fix
fixed
fixes
fixing
resolve
resolves
resolved
resolving

Relate commit to task hook:

$ git commit -m 'First part of task is done see #aBc123XyZ' 

This will only add a comment to card #aBc123XyZ with a link to the commit.

Install

First clone this repo.

$ git clone https://github.com/ricwa230/bitbucket-trello-hook.git trellohook
$ cd trellohook

Install dependencies using composer. If you have never used composer (you definitely should) you can get it from here.

$ composer install

Then you can just upload the files to a public server somewhere. I usually install it on a separate sub-domain and use SSL. To test the installation you should be able use your browser and hit the root url of the application, e.g. https://trellohook.yourdomain.com and you should see Hello BitbucketTrelloHook! in your browser window. This mean the application works, but now you have to configure it and set up the repo for POST hooks.

Configure the app

To configure the app create a file called config.json in the root of the project. The file should be a valid JSON file and have the following structure:

{
	"users": [
		{
			"alias": "marcus",
			"key": "11111111111111111111111111111111",
			"token": "22222222222222222222222222222222222222222222222222222222222222222"
		},
		{
			"alias": "peter",
			"key": "33333333333333333333333333333333",
			"token": "44444444444444444444444444444444444444444444444444444444444444444"
		}
	],
	"list": "Done",
	"emoji": ":beer:"
}

Add a valid Trello API app key and an OAuth token for each user following the instructions below. The config allows you to allow all developer/members to use the hook and to name your done list to whatever you want, just write the exact name of the "Done"-list in the config file list property. To identify each user write the Bitbucket user name in the alias property.

Sugar

In the config you can add an emoji that will show in front of the comment, so it's easy to spot commits over normal comments. I usually use 🍺 because it's probably a good time to go and grab a beer after a commit, but it's up to you and your team what you want to have! Here is a link to a emoji cheat sheet :-)

Generate Key and Token

All users need to repeat the following steps one time only.

1. The current user needs to be logged in.
2. To get the key, while still being logged in visit this link https://trello.com/1/appKey/generate and you will get a application key and secret. Write down the key in the config file for this user.
3. To get the OAuth token visit this link https://trello.com/1/authorize?response_type=token&name=BitBucket+Trello+Hook&scope=read,write&expiration=never&key=[your-key-here] in your browser still logged in as current user and replace [your-key-here] with the code obtained in step 2.
4. You will presented with a token that never expires. Write that down in the config file as well.
5. Upload the config file and continue to set up the repo.

Set up repo

To set up the repo go to Bitbucket->Repo->Settings->Hooks and add a new POST hook. In the URL-field type in the url for your newly created web app and append the boardId from Trello that you want to work against. The url should look like this:

https://trellohook.yourdomain.com/webhook/<boardId>

To get the boardId simply log in totTrello and visit the board. Copy the boardId from the address bar. The url should look something link this: https://trello.com/b/NEwlIH3D/how-to-use-trello-for-ipad where NEwlIH3D is the boardId. Use this boardId in the hook-url. Your url should then look like this:

https://trellohook.yourdomain.com/webhook/NEwlIH3D

Todo

• First implementation
• Support move card
• Support comments on card
• Support many users
• Maybe support reopen task?
• Maybe support marking items in checklist done?