Repository Commit Hooks¶

This guide explains how to set up a subversion pre-commit hook with your Planio repository. Using pre-commit webhooks, project managers can influence the commit life cycles of repositories, by for example enforcing a certain commit message format, limiting commit rights for certain portions of the subversion repository, or by enforcing other custom rules.

• Table of contents
• Repository Commit Hooks
  • Setting up your pre-commit hook
  • Web hook configuration
  • Web hook payload

Setting up your pre-commit hook¶

In your project, navigate to Settings → Repositories. Find the repository you're concerned with and click Edit. This form has a new row labelled Pre-Commit Hooks, where a click on Edit leads to the list of pre-commit hooks for that repository. Please click Add in order to create a new hook. The form, as of now, only allows creation of 'pre-commit web hooks', but this will be extended in the future to allow for post-commit web hooks as well. Other kinds of hooks may be added in the future, too.

Web hook configuration¶

Besides a name for the hook, you're required to enter your hook's URL, and you can configure a (comma-separated) list of HTTP status codes that will be considered a success (besides the HTTP 2xx codes which are considered a success by default). The general rule is that any non-successful HTTP response will let the hook, and therefore the commit, fail.

In case of a failure, any response body sent by your hook will be passed on to the committing user, if the response has a content type of text/plain. Otherwise, a generic error message ("Commit denied by repository configuration") will be given.

You can set up multiple hooks for the same repository, and reorder them using the drag handles in the table. Hook execution stops at the first failed hook, later hooks are not executed.

Web hook payload¶

The JSON payload we POST to your configured URL is very similar to the payload used by our existing post-commit hook feature. It contains information about the project, repository, and the actual commit.

Sample payload:

{
  "project":{
    "name":"Demo",
    "identifier":"demo",
    "id":10
  },
  "hostname":"demo.planio.com",
  "repository":{
    "id":45,
    "name":"hooktest",
    "full_name":"demo.hooktest",
    "html_url":"https://demo.planio.com/projects/demo/repository/45",
    "url":"https://demo.planio.com/projects/demo/repository/45",
    "issues_url":"https://demo.planio.com/projects/demo/issues.json",
    "size":90824,
    "svn_url":"https://demo.planio.com/svn/demo.hooktest"
  },
  "before":"1",
  "size":1,
  "commits":[{
    "committer":"jk",
    "message":"test commit",
    "added":[],
    "modified":["changed/file.txt"],
    "removed":[],
    "prop_changed":[]
  }],
  "head_commit":{
    "committer":"jk",
    "message":"test commit",
    "added":[],
    "modified":["changed/file.txt"],
    "removed":[],
    "prop_changed":[]
  }
}

Elements in the project and repository structures should be self-explaining. The remaining top level elements are:

• before - highest revision number before this commit
• head_commit - the last (and in the case of SVN, only) commit that is contained in this payload.
• commits - list of all commits contained in this payload (always one for SVN)
• size - number of commits contained in the payload (for SVN this will be always 1)

For consistency reasons we decided to stick to the existing payload format of the post-commit / post-receive web hooks which we already have in place for Git and SVN repositories - that's why there are the seemingly redundant commits list and separate head_commit elements, which are more useful in the case of Git.

For each commit, the login of the committing user, the log message as well as the list of added / removed / modified paths, as well as paths that had properties changed, are given.