Custom Post-Receive Hooks

Custom post-receive hooks run after changes have been successfully pushed to your Bitbucket repositories. Use them to trigger automated actions such as deployments, notifications, or logging.

Asynchronous Post Hooks

By default, custom post-hooks execute synchronously. This means that repository pushes are delayed until the post-hook has completed execution.

If your custom post-hook does not require the push to have completed before execution, you should prefer executing asynchronously. This prevents a noticeable delay in pushes to end-users. Executing asynchronously also means that post-hooks can execute in parallel.

Note: Synchronous post-hooks are not triggered by UI interactions, such as editing a file in the built-in file editor within Bitbucket.

Asynchronous execution is an opt-in because it changes some hook behaviours, such as the ability to write messages to the Git client.

To opt-in to asynchronous execution, check the Execute asynchronously checkbox:

Once asynchronous execution has been enabled, you are able to select custom triggers that only support asynchronous execution, such as file-edit.

Note: Asynchronous post-hooks are not able to write messages to the Git client on push. If your use case requires writing a message to the Git client, you must use a synchronous post-hook.

Samples

The following examples will walk you through writing a custom post-receive hook.

Note: The same variables as in pre-receive hooks are available in the binding.

Push Traceability

This relates to BSERV-2642. In this example we use a post-receive hook to store the user ID of the person that pushed commits in git notes. Note that the person pushing may not necessarily be the person that authored the commits.

If you want to validate commit authors and prevent pushing of commits that don't follow your policy, see the pre-recieve hook, Enforce Trusted Commit Authors. This post-receive hook just records the credentials of the pushing user, for later verification.

You can view the notes by fetching them and using an argument to git log:

git fetch origin refs/notes/push-traceability:refs/notes/push-traceability
git log --show-notes=push-traceability

> commit 4c0b324d36b961d384afcba3a2f831d23486e194
> Author: Administrator <admin@example.com>
> Date:   Fri Sep 11 13:48:32 2015 +0100
>
>     Added testfile
>
> Notes (push-traceability):
>     {
>         "date": "2015-09-11T02:03:17+0100",
>         "userId": 1267,
>         "userName": "jechlin"
>     }

Read more about git notes in the documentation and a helpful blog post.

The script is a Custom Post-Hook post-receive hook:

import com.atlassian.bitbucket.io.SingleLineOutputHandler
import com.atlassian.plugin.PluginAccessor
import com.atlassian.sal.api.component.ComponentLocator
import com.atlassian.bitbucket.repository.RefChange
import com.atlassian.bitbucket.repository.Repository
import com.atlassian.bitbucket.scm.git.command.GitCommandBuilderFactory
import com.atlassian.bitbucket.auth.AuthenticationContext
import com.onresolve.scriptrunner.runner.ScriptRunnerImpl
import groovy.json.JsonBuilder
import org.apache.commons.lang.SystemUtils

def repository = repository as Repository
def refChanges = refChanges as Collection<RefChange>

final String NAMESPACE = "push-traceability"

def AuthenticationContext = ComponentLocator.getComponent(AuthenticationContext)

def pluginAccessor = ComponentLocator.getComponent(PluginAccessor)
def gitCommandBuilderFactory = ScriptRunnerImpl.getOsgiService(GitCommandBuilderFactory)

def currentUser = AuthenticationContext.getCurrentUser()

def pushDetails = [

    date    : new Date().format("yyyy-MM-dd'T'hh:mm:ssZ"),
    userId  : currentUser.id,
    userName: currentUser.name,
]

def pushDetailsJson = new JsonBuilder(pushDetails).toPrettyString()
if (SystemUtils.IS_OS_WINDOWS) {
    pushDetailsJson = pushDetailsJson.replaceAll("\"", /\"/)
}

refChanges.getCommits(repository).each { commit ->
    gitCommandBuilderFactory.builder(repository)
        .command("notes")
        .argument("--ref=$NAMESPACE")
        .argument("add")
        .argument("-f")
        .argument("-m")
        .argument(pushDetailsJson)
        .argument(commit.id)
        .build(new SingleLineOutputHandler()).call()
}

In order to prevent anyone updating the notes in this namespace, you can add a Protect Git Refs pre-recieve hook, where the condition is:

refChanges.any {it.ref.id == "refs/notes/push-traceability"}

It's possible to add the push details to the commits page in the Bitbucket UI. We'll add this if there is interest.

Update Static Site

This is an example of deploying static content such as a web site to a web server. Either the head of default could be deployed, or you can make use of a floating release label, called for instance PRODUCTION. When we detect the label has moved we deploy the content to the web server.

Typically you would copy using scp or rsync, which requires password-less SSH access to the remote web server. In this example we'll just assume that the web server is serving content from a local directory for simplicity.

You could easily extend this to support additional labels, such as STAGING. The staging tag would be at or head of the production tag, and would deploy to a staging server for QA or user acceptance testing.

Note: If you are deploying to a remote web server you can avoid all of this, and just replace with a command such as:

git archive --format zip PRODUCTION | \
    ssh admin@web.acme.com -c " | tar -x -C /path/to/doc/root"

This script looks more complex than it really is. All it does is:

If the target directory doesn't exist, create it
If the target directory is empty, clone the repository
Update to the PRODUCTION tag

import com.atlassian.bitbucket.io.SingleLineOutputHandler
import com.atlassian.bitbucket.repository.RefChange
import com.atlassian.bitbucket.repository.RefChangeType
import com.atlassian.bitbucket.repository.Repository
import com.onresolve.scriptrunner.bitbucket.HookResponseAdapter
import com.onresolve.scriptrunner.canned.bitbucket.util.BitbucketBaseScript
import com.onresolve.scriptrunner.canned.bitbucket.util.BitbucketCannedScriptUtils
import groovy.transform.BaseScript

@BaseScript BitbucketBaseScript baseScript // <1>

Repository repository = repository
Collection<RefChange> refChanges = refChanges
HookResponseAdapter hookResponse = hookResponse

final def productionTag = "PRODUCTION"
final def webDirLocation = System.getProperty("java.io.tmpdir") + "/web/" // <2>

if (!refChanges.any {
    it.ref.id.startsWith("refs/tags/$productionTag") &&
        it.type in [RefChangeType.ADD, RefChangeType.UPDATE]
}) {
    log.debug("No change to tag, exiting")
    return
}

def target = new File(webDirLocation)
def handler = new SingleLineOutputHandler()

if (!target.exists()) {
    target.mkdirs()
}

if (!target.list()) { // <3>
    gitCommandBuilderFactory.builder(repository)
        .clone()
        .normal()
        .origin(repository)
        .directory(webDirLocation)
        .build()
        .call()
} else {
    gitCommandBuilderFactory.builder(repository) // <4>
        .push()
        .refspec("refs/heads/*")
        .refspec("refs/tags/*")
        .force(true)
        .repository(webDirLocation)
        .build(handler)
        .call()
}

gitCommandBuilderFactory.builder() // <5>
    .workingDirectory(webDirLocation)
    .command("checkout")
    .argument(productionTag)
    .build(handler)
    .call()

def msg = new StringBuilder("I have updated the website at $webDirLocation for you") // <6>
hookResponse.out().print(BitbucketCannedScriptUtils.wrapHookResponse(msg))

Line 10: Extend a base script, which gives us access to gitCommandBuilderFactory

Line 17: Path to web site directory, that should be updated. I am using tmp just for test purposes. This should be an empty directory, or a path that will be created.

Line 34: Target directory doesn't exist, so create a clone of this repository there

Line 43: Target directory exists, so force push all refs to it

Line 53: Checkout web dir clone to tag

Line 60: Inform the user so they can do a quick sanity check