CGI::Github::Webhook - Easily create CGI based GitHub webhooks
version 0.06
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. Takes a configuration hash (or array) as parameters.
They can be used as (Moo-style) accessors on the CGI::Github::Webhook object, too.
Path where to look for badge files. Defaults to File::ShareDir's module_dir.
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.
The CGI.pm object internally used.
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).
The mime-type used to return the contents. Defaults to 'text/plain; charset=utf-8' for now.
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 to be returned to GitHub as body if the trigger was successfully (or at least has been spawned successfully). Defaults to "Successfully triggered".
Text to be returned to GitHub as body if the authentication failed. Defaults to "Authentication failed".
Text to be returned to GitHub as body if spawning the trigger failed. Defaults to "Trigger failed".
The script or command which should be called when the webhook is called. Required.
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).
Returns true if the authentication could be verified and false else. Read-only attribute.
The payload as passed as payload in the POST request
The payload as passed as payload in the POST request if it is valid JSON, else an error message in JSON format.
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.
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.
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.
Passes arguments to $self->header and prints result to STDOUT.
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.
Axel Beckert, <abe@deuxchevaux.org>
<abe@deuxchevaux.org>
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.
bug-cgi-github-webhook@rt.cpan.org
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
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.
Axel Beckert <abe@deuxchevaux.org>
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.
To install CGI::Github::Webhook, copy and paste the appropriate command in to your terminal.
cpanm
cpanm CGI::Github::Webhook
CPAN shell
perl -MCPAN -e shell install CGI::Github::Webhook
For more information on module installation, please visit the detailed CPAN module installation guide.