The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
App-GitHooks-Plugin-NotifyReleasesToSlack-v1.1.1
River stage zero No dependents
1 ++
/ App::GitHooks::Plugin::NotifyReleasesToSlack

NAME

App::GitHooks::Plugin::NotifyReleasesToSlack - Notify Slack channels of new releases pushed from a repository.

DESCRIPTION

If you maintain a changelog file, and tag your release commits, you can use this plugin to send the release notes to Slack channels.

Here is a practical scenario:

  1. Install App::GitHooks::Plugin::NotifyReleasesToSlack.

  2. Set up an incoming webhook in Slack. This should give you a URL to post messages to, with a format similar to https://hooks.slack.com/services/.../.../....

  3. Configure the plugin in your .githooksrc file:

            [NotifyReleasesToSlack]
        slack_post_url = ...
        slack_channels = #releases, #test
        changelog_path = Changes

  4. Add release notes in your changelog file:

            v1.0.0  2015-04-12
                - Added first feature.
                - Added second feature.

  5. Commit your release notes:

            git commit Changelog -m 'Release version 1.0.0.'

  6. Tag your release:

            git tag v1.0.0
        git push origin v1.0.0

  7. Watch the notification appear in the corresponding Slack channel(s):

            release-notes BOT: @channel - Release v1.0.0 of test_repo:
        - Added first feature.
        - Added second feature.

VERSION

Version 1.1.1

CONFIGURATION OPTIONS

This plugin supports the following options in the [NotifyReleasesToSlack] section of your .githooksrc file.

        [NotifyReleasesToSlack]
        slack_post_url = https://hooks.slack.com/services/.../.../...
        slack_channels = #releases, #test
        changelog_path = Changes
        notify_everyone = true

slack_post_url

After you set up a new incoming webhook in Slack, check under "Integration settings" for the following information: "Webhook URL", "Send your JSON payloads to this URL". This is the URL you need to set as the value for the slack_post_url config option.

        slack_post_url = https://hooks.slack.com/services/.../.../...

slack_channels

The comma-separated list of channels to send release notifications to.

        slack_channels = #releases, #test

Don't forget to prefix the channel names with '#'. It may still work without it, but some keywords are reserved by Slack and you may see inconsistent behaviors between channels.

changelog_path

The path to the changelog file, relative to the root of the repository.

For example, if the changelog file is named Changes and lives at the root of your repository:

        changelog_path = Changes

notify_everyone

Whether @everyone in the Slack channel(s) should be notified or not. true by default, but can be set to false to simply announce releases in the channel without notification.

        # Notify @everyone in the channel.
        notify_everyone = true

        # Just announce in the channel.
        notify_everyone = false

METHODS

run_pre_push()

Code to execute as part of the pre-push hook.

  my $plugin_return_code = App::GitHooks::Plugin::NotifyReleasesToSlack->run_pre_push(
                app   => $app,
                stdin => $stdin,
        );

Arguments:

  • $app (mandatory)

    An App::GitHooks object.

  • $stdin (mandatory)

    The content provided by git on stdin, corresponding to a list of references being pushed.

FUNCTIONS

verify_config()

Verify that the mandatory options are defined in the current githooksrc config.

        my $plugin_return_code = App::GitHooks::Plugin::NotifyReleasesToSlack::verify_config(
                $config
        );

Arguments:

  • $config (mandatory)

    An App::GitHooks::Config object.

get_remote_name()

Get the name of the repository.

        my $remote_name = App::GitHooks::Plugin::NotifyReleasesToSlack::get_remote_name(
                $app
        );

Arguments:

  • $app (mandatory)

    An App::GitHooks object.

notify_slack()

Display a notification in the Slack channels defined in the config file.

        App::GitHooks::Plugin::NotifyReleasesToSlack::notify_slack(
                $app,
                $message,
        );

Arguments:

  • $app (mandatory)

    An App::GitHooks object.

  • $message (mandatory)

    The message to display in Slack channels.

get_changelog_releases()

Retrieve a hashref of all the releases in the changelog file.

        my $releases = App::GitHooks::Plugin::NotifyReleasesToSlack::get_changelog_releases(
                $app
        );

Arguments:

  • $app (mandatory)

    An App::GitHooks object.

get_pushed_tags()

Retrieve a list of the tags being pushed with git push.

        my @tags = App::GitHooks::Plugin::NotifyReleasesToSlack::get_pushed_tags(
                $app,
                $stdin,
        );

Arguments:

  • $app (mandatory)

    An App::GitHooks object.

  • $stdin (mandatory)

    The content provided by git on stdin, corresponding to a list of references being pushed.

BUGS

Please report any bugs or feature requests through the web interface at https://github.com/guillaumeaubert/App-GitHooks-Plugin-NotifyReleasesToSlack/issues/new. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

        perldoc App::GitHooks::Plugin::NotifyReleasesToSlack

You can also look for information at:

AUTHOR

Guillaume Aubert, <aubertg at cpan.org>.

COPYRIGHT & LICENSE

Copyright 2013-2016 Guillaume Aubert.

This code is free software; you can redistribute it and/or modify it under the same terms as Perl 5 itself.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the LICENSE file for more details.