Last week we started using the issue tracking system JIRA. To take full advantage of all features we wanted to integrate our repositories on BitBucket with JIRA - it should be easy, there is an official DVCS Connector plugin for this task.
Installation of the plugin was really smooth, after couple minutes spend on configuration, we were able to push changesets to our repository and they immediately appeared in the activity stream of the project. At the first glance it seemed that everything is working just fine, but as we tried more advanced features a problem appeared - smart tags weren't working. (Smart tags is a nice feature, that allows you to edit issues in JIRA with the commit message - e.g. LS-15 #time 15m #close)
We checked and rechecked configuration of JIRA / Bitbucket and everything seemed exactly as in the installation guide. After some tests we tracked down the problem to user accounts - the user accounts on BitBucket weren't linked to the user accounts in JIRA, since issue changes in our JIRA can be made only by authorized users, smart tags couldn't work. Both JIRA and Bitbucket accounts have the same usernames and the same emails, but it isn't enough.
After couple tries we finally found the solution - to successfully link the author of the commit with the JIRA user (and thus enable smart tags), the commit has to been made with the correct username. Is seems that BitBucket credentials are irrelevant for this case - they are necessary to push changes to BitBucket, but they aren't used by JIRA.
The username can be set in the mercurial.ini file or in UI, if you are using TortoiseHg
The correct format of the username is
e.g. Lukas Kabrt <email@example.com>
I hope this might save somebody few minutes, because this detail isn't mentioned in the documentation (or it is well hidden :-) )