Using Web Hooks

Web Hooks give you a chance to run your own scripts in response to a Subversion commit.

A pre-commit web hook can look at the commit's meta-data and decide whether to allow or deny the commit.

A post-commit web hook can trigger actions once a commit is accepted; for example running tests or posting to twitter.

 

Writing Web Hooks

Web Hooks are CGI scripts. We send meta-data about commits via POST parameters. Post-commit hooks don't need to return anything. Pre-commit hooks should return an action to take, using JSON notation.

Here is an example pre-commit script, written in Perl, which uses the description parmameter to decide whether to allow a commit, and returns 'allow' or 'deny':

 

#!/usr/bin/perl
# (C) Copyright CollabNet. Permission is granted to use and share this example file.
use warnings;
use strict;
use Data::Dumper;
use CGI;

my $cgi = CGI->new();
print $cgi->header('application/json');
#print Dumper({$cgi->Vars()});
my $commitDescription = $cgi->param('description');

if ($commitDescription =~ /\#[0-9]+/)
{
        print "{'action':'allow'}\n";
}
else
{
        print "{'action':'deny', 'reason':'No ticket number given'}\n";
}
exit 0;

 

(Note: If you are getting hook script errors after the server migration, it should be because of the old server you were hosted used a JSON parser, which did not check if it was a valid JSON, but the new server will. Hence to fix it, we will need to do the below changes. Use the double-quotes instead of single quotes in the hook script.)  The changes that needs to be done: 

 

print "{\"action\":\"allow\"}\n";

 

and: 


print "{\"action\":\"deny\", \"reason\":\"No ticket number 
given\"}\n";

 

Your scripts can be written in any language, as they are hosted and run on your own servers.

The full list of parameters we send is:

 

  • service: 'svn' for Subversion services. May take other values in future.
  • author: login name of the person who made the commit
  • project: short name of the project being committed to
  • organization: short name of the organization who owns the project (AKA domain)
  • youngest: Newest revision number in svn
  • log: The log message entered by the user for this commit
  • changed: List of what files are changed, as listed by svn.

 

For post-commit hooks, the script does not need to output anything in particular.

For pre-commit hooks, the script should output one of:

 

  • {'action':'allow'}
  • {'action':'deny', 'reason':'YOUR CUSTOM COMMIT FAILURE MESSAGE'}

 

Note that the script should "succeed", ie return an OK status and this message as the page content. The correct content type to use is 'application/json' however we ignore this field.

We suggest using the above example, perhaps adding code to log the full list of parameters your script receives so that you can explore what options you have for custom behaviours.

 

Configure Web Hooks

Assuming you already have a subversion repository and a script to try, simply visit the Admin > Global Settings section, click Commit Hooks, and enable one of the hooks in the 'web hooks' section. More details here

Configuration options are:

 

  • Script URL: Where our system can find your script. You might like to visit the URL in a browser to confirm it works first.
  • (pre-commit) Timeout:  How long should our system wait for your script to respond before it gives up?
  • (pre-commit) Default Action: Should we allow or deny commits if your script gives an error or fails to respond in time?

 

Commit Denied: What Users See

If you deny a commit, users will see an error message like this one:

 

$ svn commit -m 'added code'
Sending        file
Transmitting file data .svn: Commit failed (details follow):
svn: Commit blocked by pre-commit hook (exit code 255) with output:
Got 1 errors:
 * Commit denied by web hook: No ticket number given
 (ref devsvn01:ZT1d8RDXzrVneEW4)

 

The 'No ticket number given' message comes from our example commit hook; you can customize what this displays.

The 'ref' number is a tracking ID for our own logs, so that we can discover more details should you need to contact support.

Have more questions? Submit a request

0 Comments

Article is closed for comments.