CGI::G...ebhook(3pm)

💖 CGI::Github::Webhook 💖

okay bestie, gather round, because we're about to talk about CGI::Github::Webhook — it's the Perl module (you'll find it chillin' in the User Contributed Perl Documentation section of your manual pages, so like, section 3pm, iykyk) that lets you spin up GitHub webhooks with plain old CGI and literally zero drama. ✨

---

🌸 NAME 🌸

CGI::Github::Webhook — Easily create CGI based GitHub webhooks. that's it, that's the whole vibe. no cap.

---

🎀 VERSION 🎀

version 0.06

---

🦋 SYNOPSIS 🦋

So CGI::Github::Webhook lets you easily create simple, CGI-based GitHub webhooks. bestie, it's giving effortless.

#!/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();

look at her. she's so simple. she's so clean. she ate. 💅

---

👑 CONSTRUCTOR 👑

✨ new ✨

Constructor, periodt. It takes a configuration hash (or an array, if that's your thing) as parameters.

Here's the full list of parameters for the new() constructor.

💡 pro tip: they can also be used as (Moo-style) accessors on the CGI::Github::Webhook object, too. so cute.

badges_from

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

badge_to

Local path to the file where <https://shields.io/> style badges should be written. Defaults to undef, which means the whole feature is disabled (she's off duty 💤).

It 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 that's internally used. it's the behind-the-scenes girlie.

log

Where to send the trigger's output to. Defaults to /dev/stderr, i.e. it 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 using the output of makepasswd(1), apg(1), pwgen(1) or using Crypt::GeneratePassword to generate a randon and secure shared password.

🚨 bestie, it's required. do not skip her.

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). so like, she runs in the background and you don't have to wait around for her 💅

---

🌈 OTHER PROPERTIES 🌈

authenticated

Returns true if the authentication could be verified and false else. Read-only attribute. she said "no edits, look only" 💅

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 the file given as parameter to the path given via the 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. she's just gonna sit there and vibe. 🙈

💜 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. the way she's out here returning three different things... iconic behavior, honestly.

---

✨ 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>.

(ngl the "via via" in there is a whole mood, but we're keeping it exactly as she is 💅)

---

🫶 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.

---

and that's the whole page, bestie — no crumbs left behind 💖

so this was CGI::G...ebhook(3pm), churned out by perl v5.32.0 and dated 2021-01-08, straight out of the User Contributed Perl Documentation crew. go forth and webhook responsibly, and remember: generate that secret for real. mwah. 🎀✨🦋💅