NAME

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

VERSION

version 0.01

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.

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

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 or feature requests to bug-cgi-github-webhook at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CGI-Github-Webhook. 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 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.

cpanm CGI::Github::Webhook

perl -MCPAN -e shell
install CGI::Github::Webhook