Slack Integration Plugin
========================

A simple Gerrit plugin that allows the publishing of certain Gerrit events
to a configured Slack Webhook URL. The plugin uses Gerrit's inherited project
configuration support so common config options can be set at a higher level
and shared by many projects along with project specific config options.


Development
-----------

To build the plugin,
[JDK 1.8](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html)
and [Bazel](https://bazel.build/) are required.

Once installed use _bazel_ to build.

    cd ./slack-integration
    bazel build slack-integration

Once packaged, you can install the _./bazel-bin/slack-integration.jar_ file into
Gerrit.


Installation
------------

Installing the Slack Integration Plugin is as simple as copying the resulting
JAR file into the Gerrit plugins directory. Assuming you installation of Gerrit
is located at _/usr/local/gerrit_ you simply execute the following.

    cp ./slack-integration.jar /usr/local/gerrit/plugins

Simple substitute the path to your Gerrit plugins directory as needed. Gerrit
automatically loads new plugins and unloads old plugins, no restart is
required.


Configuration
-------------

The first thing you need to do is setup an incoming webhook integration in
Slack. This is done via my.slack.com - Configure Integrations.

Configuration of the Slack Integration Plugin is done in Gerrit via a project
specific config file. This configuration is stored in the project’s
_project.config_ file on the _refs/meta/config_ branch of the project.

Common configuration options that can be shared between multiple projects
can be placed in the _All-Projects_ config branch, or another project that
serves as an inherited base. Config options can then be overridden in the
actual project's config branch. For example, you may want to specify a default
webhook URL, username and channel then override the channel to be specific
to each project.

Editing a project's config

    mkdir <project>-config
    cd <project>-config
    git init
    git remote add origin ssh://<admin-user>@<gerrit-host>:29418/<project>
    git fetch origin refs/meta/config:refs/remotes/origin/meta/config
    git checkout meta/config

Create the following config block

    vi project.config

    [plugin "slack-integration"]
        enabled = true
        webhookurl = https://<web-hook-url>
        channel = general
        username = gerrit
        ignore = "^WIP.*"

Commit and push changes

    git commit -a
    git push origin meta/config:meta/config


Configuration Options
---------------------

The following configuration options are available

    enabled – boolean (true/false)
        When true, enables Slack integration (defaults to false).
    webhookurl - String
        The Slack webhook URL to publish to (defaults to an
        empty string).
    channel - String
        The Slack channel to publish to (defaults to "general").
    username - String
        The Slack username to publish as (defaults to "gerrit").
    ignore - Pattern
        A "dotall" enabled regular expression pattern that, when matches
        against a commit message, will prevent the publishing of patchset
        created event messages (defaults to an empty string).
    ignore-unchanged-patch-set - boolean (true/false)
        Whether a Slack notification about a new patch-set shouldn't be
        published when code didn't change (defaults to true).
    ignore-wip-patch-set - boolean (true/false)
        Whether any Slack notifications regarding a work-in-progress change
        shouldn't be published (defaults to true).
    ignore-private-patch-set - boolean (true/false)
        Whether any Slack notifications regarding a private change shouldn't
        be published (defaults to true).
    ignore-comment-author - Pattern
        A "dotall" enabled regular expression pattern that, when matches
        against the comment author username, will prevent the publishing
        of comment added event messages (defaults to an empty string).
    publish-on-patch-set-created - boolean (true/false)
        Whether a Slack notification should be published when a new patch set
        is created.
    publish-on-change-merged - boolean (true/false)
        Whether a Slack notification should be published when a change is
        merged.
    publish-on-comment-added - boolean (true/false)
        Whether a Slack notification should be published when a comment is
        added to a review.
    publish-on-reviewer-added - boolean (true/false)
        Whether a Slack notification should be published when a reviewer is
        added to a review.
    publish-on-wip-ready - boolean(true/false)
        Whether a Slack notification should be published when a
        work-in-progress change is marked ready (defaults to the value for
        publish-on-patch-set-created).
    publish-on-private-to-public - boolean(true/false)
        Whether a Slack notification should be published when a
        private change is changed to public (defaults to the value for
        publish-on-patch-set-created).
   
        
Proxy Configuration
-------------------

If a proxy is needed to connect externally to Slack, a proxy server may
be configured via Gerrit's main configuration file. The path to this file will
vary based on where Gerrit was installed. This example assumes that Gerrit was 
installed in _/usr/local/gerrit_.

Edit _/usr/local/gerrit/etc/gerrit.config_ and add the following block.

    [plugin "slack-integration"]
        proxy-host = <hostname or IP address of the proxy server>
        proxy-port = <port of the proxy server>


Proxy Configuration Options
---------------------------

The following configuration options are available
    
    proxy-host - String
        The host of the proxy server, e.g. my.proxy.host (defaults to null).
    proxy-port - int
        The port of the proxy server (defaults to 8080)
    proxy-username - String
        The username, if needed, to authenticate to the proxy server 
        (defaults to null).
    proxy-password - String
        The password, if needed, for the specified username to authenticate to 
        the proxy server, (defaults to null).