With this built-in post-receive hook, your Bitbucket instance will send email notifications automatically after a post-receive hook has been triggered.

In order to configure it, a list of repositories for which this trigger will be in effect must be provided, as well as some other information related to the email that will be sent: subject and email templates, email format (plain text or HTML), a list of "to" email addresses and an optional list of "cc" email addresses.

This functionality will mostly require the use of a condition, to avoid sending emails every time something is pushed to a set of repositories.

The following is a basic configuration of the post hook to watch all commits in the repository "test" that involve a file with the .adoc extension:

With that configuration and after pushing some commits to the repository, you could get an output like the one shown in the following email:

The repository output from the example Send Mail configuration.

There are some useful links to the Bitbucket instance which will only appear in the HTML version of the notification, more specifically you will have access to the Project, Repository, Commit and Change pages.

This functionality can be also configured to send plain text emails, in which case the output would look like the the one in the following screenshot:

An example plain text email.

The content of the "to addresses" and "cc addresses" should be a list of emails separated by commas or spaces, being the following two examples correct: - email1@company.com, email2@company.com - email1@company.com email2@company.com

Customizing Your Templates

Here are three extremely simple examples to illustrate how an email template can be customized making use of some helper methods which are available in the binding:

  • Show all ref changes:

    List of all refChanges:
    <% refChanges.each { refChange -> %>
    - Commits pushed to ${refChange.ref.id}
    <% } %>
    

  • Show all commits:

    List of all commmits:
    <% refChanges.getCommits(repository).each { commit -> %>
    - ${commit.author.name} | ${commit.displayId} | ${commit.message} | ${commit.authorTimestamp}
    <% } %>

  • Show all change sets and their details:

    List of all changesets and the paths to the files changed:
    <%
        refChanges.each { refChange ->
            refChange.getChangesets(repository).each { changeset ->
    %>
    - ${changeset.toCommit.author.name} | ${changeset.toCommit.displayId} | ${changeset.toCommit.message} | ${changeset.toCommit.authorTimestamp} | ${changeset.changes.values.size()} files changed
    <% changeset.changes.values.each { change -> %>
    ${change.path.toString()}, ${change.type.toString().toLowerCase()}
    <% }}} %>

Additional Configuration in Emails

You may notice the syntax for getting content in the template is a bit clunky, as the template engine does not allow you to use the import keyword. Rather than doing this, you can pass in a config map to the bindings for both the subject and body templates. This is done in the Mail configuration section.

A simple example of a Mail configuration section that defines config variables when changes are pushed to the repository is:

`!`config.changes = ""

def refChanges = refChanges.collect { refChange ->
    config.changes += "- Commits pushed to ${refChange.ref.id}\n"
}
`!`
GROOVY

The body template:

List of all refChanges:

$config.changes
GROOVY

As a result of that configuration, an email will be sent to the selected email addresses with content similar to the following one:

List of all refChanges:
- Commits pushed to refs/heads/master
GROOVY