NAME

       CGI::Github::Webhook - Easily create CGI based GitHub webhooks

VERSION

       version 0.06

SYNOPSIS

       CGI::Github::Webhook allows one to easily create simple, CGI-based GitHub webhooks.

           #!/usr/bin/perl

           use CGI::Github::Webhook;

           my $ghwh = CGI::Github::Webhook->new(
               mime_type => 'text/plain',
               trigger => '/srv/some-github-project/bin/deploy.pl',
               trigger_backgrounded => 1,
               secret => 'use a generated password here, nothing valuable',
               log => '/srv/some-github-project/log/trigger.log',
               ...
           );
           $ghwh->run();

CONSTRUCTOR

   new
       Constructor. Takes a configuration hash (or array) as parameters.

       List of parameters for new() constructor.

       They can be used as (Moo-style) accessors on the CGI::Github::Webhook object, too.

       badges_from

       Path where to look for badge files. Defaults to File::ShareDir's module_dir.

       badge_to

       Local path to file to which <https://shields.io/> style badges should be written. Defaults
       to undef which means the feature is disabled.

       Needs to have a suffix. That suffix will then be used to look for a file in the right
       format.

       Currently only ".svg" and ".png" suffixes/formats are supported if no custom badge set is
       used.

       cgi

       The CGI.pm object internally used.

       log

       Where to send the trigger's output to. Defaults to '/dev/stderr', i.e. goes to the web
       server's error log. Use '/dev/null' to disable.

       For now it needs to be a path on the file system. Passing file handles objects doesn't
       work (yet).

       mime_type

       The mime-type used to return the contents. Defaults to 'text/plain; charset=utf-8' for
       now.

       secret

       The shared secret you entered on GitHub as secret for this trigger. Currently required. I
       recommend to use the output of makepasswd(1), apg(1), pwgen(1) or using
       Crypt::GeneratePassword to generate a randon and secure shared password.

       text_on_success

       Text to be returned to GitHub as body if the trigger was successfully (or at least has
       been spawned successfully). Defaults to "Successfully triggered".

       text_on_auth_fail

       Text to be returned to GitHub as body if the authentication failed. Defaults to
       "Authentication failed".

       text_on_trigger_fail

       Text to be returned to GitHub as body if spawning the trigger failed. Defaults to "Trigger
       failed".

       trigger

       The script or command which should be called when the webhook is called. Required.

       trigger_backgrounded

       Boolean attribute controlling if the script or command passed as trigger needs to be
       started backgrounded (i.e. if it takes longer than a few seconds) or not. Defaults to 1
       (i.e. that the trigger script is backgrounded).

OTHER PROPERTIES

       authenticated

       Returns true if the authentication could be verified and false else. Read-only attribute.

       payload

       The payload as passed as payload in the POST request

       payload_json

       The payload as passed as payload in the POST request if it is valid JSON, else an error
       message in JSON format.

       payload_perl

       The payload as perl data structure (hashref) as decoded by decode_json. If the payload was
       no valid JSON, it returns a hashref containing either { payload => 'none' } if there was
       no payload, or { error => ... } in case of a decode_json error had been caught.

SUBROUTINES/METHODS

   deploy_badge
       Copies file given as parameter to path given via badge_to attribute. The parameter needs
       to be given without file suffix. The file suffix from the badges attribute will be
       appended.

       Doesn't do anything if badge_to is not set.

   header
       Passes arguments to and return value from $self->cgi->header(), i.e. a shortcut for
       $self->cgi->header().

       If no parameters are passed, $self->mime_type is passed.

   send_header
       Passes arguments to $self->header and prints result to STDOUT.

   run
       Start the authentication verification and run the trigger if the authentication succeeds.

       Returns true on success, false on error. More precisely it returns a defined false on
       error launching the trigger and undef on authentication error.

AUTHOR

       Axel Beckert, "<abe@deuxchevaux.org>"

BUGS

       Please report any bugs, either via via GitHub Issues at
       <https://github.com/xtaran/CGI-Github-Webhook/issues> or via the CPAN Request Tracker by
       sending an e-mail to "bug-cgi-github-webhook@rt.cpan.org" or submitting a bug report
       through the CPAN Request Tracker web interface at
       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CGI-Github-Webhook>.

SUPPORT

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

           perldoc CGI::Github::Webhook

       You can also look for information at:

       •   RT: CPAN's request tracker (report bugs here)

           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=CGI-Github-Webhook>

       •   AnnoCPAN: Annotated CPAN documentation

           <http://annocpan.org/dist/CGI-Github-Webhook>

       •   CPAN Ratings

           <http://cpanratings.perl.org/d/CGI-Github-Webhook>

       •   Search CPAN

           <https://metacpan.org/release/CGI-Github-Webhook>

LICENSE AND COPYRIGHT

       Copyright 2016 Axel Beckert.

       This program is free software; you can redistribute it and/or modify it under the terms of
       either: the GNU General Public License as published by the Free Software Foundation; or
       the Artistic License.

       See <http://dev.perl.org/licenses/> for more information.

AUTHOR

       Axel Beckert <abe@deuxchevaux.org>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2016 by Axel Beckert.

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