cweagans/hookreceiver repository overview

⁠Hookreceiver

Listens for webhooks from code hosting services and executes one or more shell commands when a notification is received.

Currently supported hooks:

• Bitbucket POST Hook⁠: Use http://your-host:8080/hooks/bitbucket/repo_name for the URL.
• Gitlab Push Hook⁠: Use http://your-host:8080/hooks/gitlab/repo_name for the URL.
• Stash POST service webhook⁠: Use http://your-host:8080/hooks/stash/repo_name for the URL.
• Generic Hook that does not parse the payload: Use http://your-host:8080/hooks/generic/repo_name for the URL.

⁠Installation

⁠Manual installation

Download the binary from the latest release on Github and put it in your $PATH somewhere.

⁠Docker

docker run -v ./conf:/etc/hookreceiver.conf.d cweagans/hookreceiver:latest

Make sure that ./conf contains one or more configuration files.

⁠Build from source

• Install the Go toolchain
• Clone this repo
• Run go build (no external dependencies are needed)

⁠Usage

$ hookreceiver -h
Usage of hookreceiver:
  -c="/etc/hookreceiver.conf.d": Config path (file or directory)

⁠Configuration format

Configuration files are JSON files. You define the adress/port hookreceiver will listen on (Addr) and an array of repository configurations. When a notifaction is received for one of the configured repositories identified by URL the given commands are executed with /bin/sh -c in the working directory set with Dir.

URL indicates the canonical URL of the repository. For example when using Bitbucket this is https://bitbucket.org/user/repo.

Instead of using the URL property you can use Name. This is the repo_name part in the hookreciever URL. If you configure your repository to call http://your-host:8080/hooks/bitbucket/bar the Name would be bar. Using the name allows to configure repository providers that do not include the URL in their payload like Stash or the Generic provider.

{
  "Addr": ":8080",
  "Repositories": [
    {
      "URL": "https://bitbucket.org/srt/foo",
      "Command": [
        "git pull"
      ],
      "Dir": "/var/www/foo"
    },
    {
      "Name": "bar",
      "Command": [
        "git pull"
      ],
      "Dir": "/var/www/bar"
    }
  ]
}

⁠Configuration Directory

As an alternative you can use a configuration directory. All files in that directory will be merged to form the configuration. This makes it easy to use hookreceiver with puppet and similar systems.

00-main.conf:

{
  "Addr": ":8080"
}

01-foo.conf:

{
  "Repositories": [
    {
      "URL": "https://bitbucket.org/srt/foo",
      "Command": [
        "git pull"
      ],
      "Dir": "/var/www/foo"
    }
  ]
}

02-bar.conf:

{
  "Repositories": [
    {
      "Name": "bar",
      "Command": [
        "git pull"
      ],
      "Dir": "/var/www/bar"
    }
  ]
}

⁠Provider-specific notes

⁠Bitbucket

Use http://your-host:8080/hooks/bitbucket/repo_name for the URL.

Bitbucket supports the Name and URL configuration properties. The URL is of the form https://bitbucket.org/user/repo.

You can also restrict the command to notifications that contain changes for a specific branch using the Branch property. You may miss some commits as Bitbucket only provides detailed information like affected files and branches if pushes do not exceed a certain size limit. Thus using the Branch property is generally discouraged.

Example:

{
  "Repositories": [
    {
      "URL": "https://bitbucket.org/srt/foo",
      "Branch": "develop",
      "Command": [
        "git pull"
      ],
      "Dir": "/var/www/foo"
    }
  ]
}

See also: https://confluence.atlassian.com/display/BITBUCKET/POST+hook+management⁠

⁠Gitlab

Use http://your-host:8080/hooks/gitlab/repo_name for the URL.

Gitlab supports the Name and URL configuration properties. The URL is of the form https://gitlab.example.com/group/repo. This is the value Homepage in the JSON payload.

See also: http://doc.gitlab.com/ce/web_hooks/web_hooks.html⁠

⁠Stash

Use http://your-host:8080/hooks/stash/repo_name for the URL.

Stash does not include the canonical URL in the payload so hookreciever is unable to match a stash repository via URL. Use Name instead of URL to configure Stash hooks.

See also: https://confluence.atlassian.com/display/STASH/POST+service+webhook+for+Stash⁠

⁠Generic

Use http://your-host:8080/hooks/generic/repo_name for the URL.

The Generic provider does not parse the payload so it can be used to support arbitray systems. Use Name instead of URL to configure Generic hooks.

⁠License

Hookreceiver is released under the MIT License⁠.

⁠Acknowledgements

• Thanks to @srt for writing the original version of hookreceiver.