Custom Post-Receive Hooks
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.
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.
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.
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 master
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.
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
tagimport 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