Last year, Santa lost his mind with missing gifts, hence he gathered a council with the elves and they decided to make the process more "rigorous" in 2023. This year, it has been decided to use a GitHub repository to organize and track the preparation of gifts for Christmas.

Santa has created a repository called "gifts" in his account "santa".

Each time an elf has finished preparing a toy, he commits a quick note and a helpful message, e.g. "A cowboy for James".

So far, "What is the relation with Perl?" you might ask. It's just a great opportunity to discover and use Pithub :)

Look at last prepared toys (commits)

Every once in a while, Santa -- or the elves themselves -- want to check produced items, so they use Pithub for that:

use Pithub::Repos ();

my $repos  = Pithub::Repos->new;
my $result = $repos->commits->list( user => 'santa', 
                                    repo => 'gifts' );

while ( my $row = $result->next ) {
    print $row->{commit}->{message} . "\n";
}

It produces this kind of output:

    A bicycle for Tom
    A Barbie for Lisa
    A Transformer for Billy

Gifts should remain a surprise!

But wait, a public GitHub repository means any little young programmer frequenting GitHub will know in advance his Christmas present?! This is not good at all, so Santa decided to change visibility of the repository to "private".

It seemed at first to work well but, sadly, even though Santa and the elves could still access the repo via the GitHub UI, they were no longer able to list the commits via Pithub.

They started to debug by adding some error handling:

unless ( $result->success ) {
    printf "Error: %s\n", $result->response->status_line;
    exit 1;
}

This confirmed that the repository is "not visible" with Error: 404 Not Found

Fortunately, there is a solution to this: use a "token" to authenticate the access!

The elves asked Santa to create one in the GitHub UI from settings/tokens:

The elves provided the generated token to the Pithub constructor and regained access to the private repository:

use Pithub::Repos ();

my $repos  = Pithub::Repos->new(token => 'ghp_pwBR12');
my $result = $repos->commits->list(user => 'santa', 
                                   repo => 'gifts');

unless ( $result->success ) {
    printf "Error: %s\n", $result->response->status_line;
    exit 1;
}

while ( my $row = $result->next ) {
    print $row->{commit}->{message} . "\n";
}

Using a token also allows you to increase your GitHub API rate limit.

Sending gifts

To alert when a toy is about to be delivered, the elves are opening Pull Requests, and they once again use Pithub for this.

Each elf is doing one Pull Request per family, and after Santa actually delivers the toys he merges the Pull Requests. (Don't ask me to elaborate a full branching model).

It's a little bit of work, but once again very easy and straightforward:

use Pithub::PullRequests ();

my $pull  = Pithub::PullRequests->new(token => 'ghp_pwBR12');

print "Create PR from [family-anderson] to [main]\n";
$result = $pull->create(
    user  => 'santa',
    repo  => 'gifts',
    data   => {
        base  => 'main',
        body  => 'Delivery to family Anderson',
        head  => 'family-anderson',
        title => 'Family Anderson',
    }
);

unless ( $result->success ) {
    printf "Error: %s\n", $result->response->status_line;
    exit 1;
}

Conclusion

Thanks to Pithub, the elves were able to easily interact with the GitHub API for both reading and writing.

If Christmas is once again a success this year, some of the credit should go to Pithub!