From 956f009672679c5e5d8b152ba8b642442f8c9492 Mon Sep 17 00:00:00 2001
From: Nikola Knezevic <nikola@knezevic.ch>
Date: Thu, 26 Mar 2020 10:02:41 +0100
Subject: [PATCH] Add documentation for SlackNotification plugin
---
src/lib/Hydra/Plugin/SlackNotification.pm | 50 ++++++++++++++++++++++-
1 file changed, 49 insertions(+), 1 deletion(-)
diff --git a/src/lib/Hydra/Plugin/SlackNotification.pm b/src/lib/Hydra/Plugin/SlackNotification.pm
index 96933c51..97810516 100644
--- a/src/lib/Hydra/Plugin/SlackNotification.pm
+++ b/src/lib/Hydra/Plugin/SlackNotification.pm
@@ -7,6 +7,53 @@ use LWP::UserAgent;
use Hydra::Helper::CatalystUtils;
use JSON;
+=head1 NAME
+
+SlackNotification - hydra-notify plugin for sending Slack notifications about
+build results
+
+=head1 DESCRIPTION
+
+This plugin reports build statuses to various Slack channels. One can configure
+which builds are reported to which channels, and whether reports should be on
+state change (regressions and improvements), or for each build.
+
+=head1 CONFIGURATION
+
+The module is configured using the C<slack> block in Hydra's config file. There
+can be multiple such blocks in the config file, each configuring different (or
+even the same) set of builds and how they report to Slack channels.
+
+The following entries are recognized in the C<slack> block:
+
+=over 4
+
+=item jobs
+
+A pattern for job names. All builds whose job name matches this pattern will
+emit a message to the designated Slack channel (see C<url>). The pattern will
+match the whole name, thus leaving this field empty will result in no
+notifications being sent. To match on all builds, use C<.*>.
+
+=item url
+
+The URL to a L<Slack incoming webhook|https://api.slack.com/messaging/webhooks>.
+
+Slack administrators have to prepare one incoming webhook for each channel. This
+URL should be treated as secret, as anyone knowing the URL could post a message
+to the Slack workspace (or more precisely, the channel behind it).
+
+=item force
+
+(Optional) An I<integer> indicating whether to report on every build or only on
+changes in the status. If not provided, defaults to 0, that is, sending reports
+only when build status changes from success to failure, and vice-versa. Any
+other value results in reporting on every build.
+
+=back
+
+=cut
+
sub isEnabled {
my ($self) = @_;
return defined $self->{config}->{slack};
@@ -44,9 +91,10 @@ sub buildFinished {
my $jobName = showJobName $b;
foreach my $channel (@config) {
- my $force = $channel->{force};
next unless $jobName =~ /^$channel->{jobs}$/;
+ my $force = $channel->{force};
+
# If build is cancelled or aborted, do not send email.
next if ! $force && ($b->buildstatus == 4 || $b->buildstatus == 3);