Setting up a repository hook with JSON

The use the notification hook in Notifyr  a JSON configuration must be added to the root of your source code. The advantage of having a JSON file that is part of your source code is that:

  • You can include a default setting in your project architecture.
  • Developers can include their own notification if required
  • Much more flexibility on type of notifications based on branches

Prepare your repository for the notification hook

For a repository to use the notification hook, a JSON file named notifications.json needs to be added to the root of the repository. A bare minimum notifications.json file would looks like this:

minimum notifications.json
{
	"rules": [{
		"notifications": [{
			"address" : "[email protected]"
		}]
	}]
}

The above configuration would send a notification to [email protected] for every push made to the repository. 

The JSON configuration has more options and flexibility in when to send what kind of notification and to who. Take the following configuration for example:

notifications.json
{
  "rules": [
    {
        "match": "/**/feature/*",
		"inverted" : false,
        "notifications" : [
            {
                "address" : "[email protected]",
                "sendSeparate" : true,
                "includeDiff" : true
            },
            {
                "address" : "[email protected]",
		        "prefix" : "[HOOK]"
            }
        ]
    },
    {
        "match": "/**/*",
        "notifications": [
            { "address": "[email protected]" }
        ]
    }
  ]
}

There are a few thing happening here, but first thing you might noticed is that you are able to specify multiple rules. Let's explain the options

matchAn Ant based pattern to match your branch against
/**/* matches all branches (default)
/**/feature/* matches all feature branches
invertedtrue or false should the result from the match be inverted? Defaults to false
notifications

an array of notifications:

addressThe email address to send the notification to
prefixThe email subject prefix. Uses the system default if not specified
sendSeparateSet to true if you want to receive separate emails per commit
includeDiffSet to true if you want to include a file diff
onBranchCreatedSet to false when you don't want to receive notification on newly created branches. Default to true


Enable to Notification Hook

Repository administrators can setup the hooks that are available in Bitbucket by going to Settings > Hooks for a Bitbucket repository. Once installed, hooks are available across all repositories in a Bitbucketinstance, but are enabled separately on each repository in a project. 

To setup the Notification Hook:

  • Browse to the Hooks overview in your repository settings
    • Browse to the relevant repository
    • Choose Settings from the repository navigation
    • Select Hooks from the left menu
  • Toggle the Notifyr - Notification Hook setting to Enabled.