Site announcement

We are switching off article comments on this website. Read about the upcoming changes to Atlassian Documentation.

Skip to end of metadata
Go to start of metadata

With this hook, you can set up Bitbucket to change the state of a given issue, based on the commit message in an update. The Issues hook scans commit messages for keywords.  You can use these keywords to automatically change the state of an issue on your repository's issue tracker.

If you enabled an issue tracker on your repository after August 2012, the Issue hook is enabled automatically for you.  Older repositories with older issue trackers may or may not have this hook enabled.  You can check if this hook is enabled by going to the Hooks tab on your repository settings:

If you are having trouble with the hook, see Troubleshooting Bitbucket hooks.

Enabling the hook manually

  1. Log into Bitbucket and navigate to the repository you want to modify.
  2. Click the settings icon .
  3. Click Hooks on the left-hand side of the screen.
  4. Select the Issues hook from the Select a hook list.
  5. Click Add hook. That's it – done.

Putting the Issue Keywords into your Commit Message

To link commit to an issue from a commit message, include an command-issue pair somewhere in your commit message. This pair takes the following format:

<command> <issue id>

You can link to a single issue or multiple issues.  The <issue id> can take an of the following forms:

issue #4711
bug #4711
ticket #4711

You should always include the # (pound sign or hash mark) if you to ensure that links back to the issue resolve.  If you omit the # (pound sign or hash mark), links from a changeset do not resolve.

Each action supports multiple <command> keywords. The following table lists the actions you can perform through a commit and the acceptable commands for that action.  All the keywords are case insensitive. So, for example, both close and Close work to close an issue.

ActionCommand KeywordExamples
resolve an issue
  • close
  • closes
  • closed
  • closing
  • fix
  • fixed
  • fixes
  • fixing
  • resolve
  • resolves
  • resolved
  • resolving

close #845

fix bug #89

fixes issue 746

resolving #3117
reopen an issue
  • reopen
  • reopens
  • reopening
reopen #746

reopening #78

mark an issue on hold
  • hold
  • holds
  • holding
holds #123
mark an issue wontfix
  • wontfix
wontfix #12
mark an issue invalid
  • invalidate
  • invalidates
  • invalidated
  • invalidating
invalidates #45
link to a changeset for the issue
  • addresses
  • re
  • references
  • ref
  • refs
  • see
re bug #55

see #34 and #456



  1. Anonymous

    It would be good to be able to open a new bug from a commit message. For example, with a 'TODO' or 'FIXME' tag.

    Watch the BB-5107 issue to vote up this feature request.

  2. Anonymous

    I agree with both your comments! Especially the second (TODO/FIXME)!

  3. Anonymous

    It seems that these commands are not recognized if put between parenthesis

    (fixes #1)

    does not close the issue, probably because there is no space before the command.

    1. That's unfortunate because I certainly understand the desire to separate this from the main commit message in some way. Thanks for reporting it. I've taken to using this:

      Some commit message / Fixes #1

  4. Anonymous

    can you also add 'refers' as a synonym of 'refs', 'see'..? thanks

    1. Anonymous

  5. Anonymous

    Is there any plan to enhance this services by allowing us to have richer email interface to the Bitbucket's tracker?

    I'm thinking about stuff similar to Launchpad's  Email Interface.

    At the moment we're evaluating hg/bb vs bzr/lp (see this question) and if bb would have it, we wouldn't consider anything else.

  6. I'm having problems where the commit messages in my private repository are not making any change, or being attached to, any issues associated with that repo. Is this a known issue? I have a free account and have enabled the Issues service.

    1. Hi, Richard.

      Commits to your private repository do not propagate to any other repositories unless you issue the appropriate hg push command to share those updates. If you haven't pushed your commits to Bitbucket, the service won't have seen those commit messages in order to apply them to your Issues.

      For an experienced Mercurial user, this is obvious. I don't mean in any way to be insulting: it's just possible that some people -- especially those coming from a centralized repository system, such as Subversion – may be confused on this point.

      I just activated the Issues service and it's working great for me.

      If you are pushing commits to Bitbucket but not seeing the messages affect the Issues, would you be willing to give an example of a commit message so we can be sure you are doing it correctly? Also, are you using Mercurial from the command-line or some sort of GUI tool?

      1. Fergus,

        Thanks for taking a look at this. I've got a ticket open with support, and need to enable the POST service on that repo to help them troubleshoot. Until then...


        Private repo, with ISSUES server enabled.

        Commit to local, push to private, with message "Fix blah. Close #1"

        No message appended to issue 1, no status change.

        So, my question to you is: did you activate the ISSUES service on a public or private repo?

        1. I commit and push with " append3 close #1 fix #1",

          "No message appended to issue 1, no status change."

          You can see the changesets

  7. Anonymous

    When you are working with a fork of another project and you import commits from the original project sometimes they use the same service. This leads to a conflict:

    if I import a commit like this: "Better handling the *something* system. Fixes #4150"

    Maybe in my project that issue is #179, is not present or, worst of all, #4150 is another issue.

    So why not implementing a system to customize Keywords to enable each project to use his own standard and to avoid this conflicts?

  8. Anonymous

  9. Anonymous

    Strange, I can see an issue from changeset but cant see changesets from an issue.

    1. Anonymous

      Same happens for me. I see a issue link inside my revision comments, but don't see any commit comments inside my issue. Is that the expected behavior?

  10. Anonymous

    Is it possible to have it working the opposite way? I mean, instead of adding issue information into the commit details, it would be great to add commit details into the issue itself. Thus, it would be possible to see all the commits related a given issue from inside it.

    I've already seem it working on Bugzilla and it was great to have all the commits history for a given issue listed inside it.

    1. Anonymous

    2. Anonymous

    3. Hi,

      This is an interesting suggestion for an enhancement.  The best thing to do is create an issue for it as our development team does not always track the page comments.  You can do that in our bitbucket issue tracker here:

      Alternatively, you can get a 10 user Starter license for JIRA and track your issues in JIRA by setting up the DVCS Connector for your bitbucket repo. The DVCS connector already provides this functionality.



  11. Anonymous

  12. Anonymous

    Is it possible to add customization to keywords (e.g. when commit messages are no English?)


    1. Anonymous

  13. Anonymous

  14. Anonymous

    Is it by design for merges to add a new comment to issue? For example, I push a fix to tracked branch, it resolves the bug and adds a comment correctly. When I merge the branch into master, it adds the comment again. Is there any way to stop this from happening? Alternatively, if the message was not identical, but a merge message, that would be good too.

    1. Hi,

      Yes, bitbucket considers the branch and the master two different repos. Whaty ou are really requesting an enhancement. The best thing to do is create an issue for it.  You can do that in our bitbucket issue tracker here:




  15. Anonymous

    BUG, git commit message: "blah-blah fix #2" -> not resolve issue #2

    1. Anonymous

      You need to add the Service Issues.  Go to Admin -> Services -> Selecet 'Issues' in the dropdown -> Click in Add Button then Save Settings...

  16. This is now enabled by default. Thank you everyone for your feedback!

  17. Anonymous

    putting: Issue #5 links the commit to the issue so that you can go to the issue.

    But is there any command by which a comment will be added to the issue linking the commit and if user clicks on commit, he can see the commit instance. This way he can track the changes made for a particular ticket.

    JIRA has this facility and I have been using in my corporate JIRA application. Was wondering if this feature is available with bitbucket version of issues.

    1. We do cross-reference from the issue to the commit and from the commit to the issue. I'll update the documentation.

  18. Anonymous

    Maybe a tag to Create and Close Issue automatically (e.g CREATECLOSEBUG) can help to increase the development produtivity.