Net::G...:Repos(3pm)

📦
version 1.05 · 3 versions
, in ubuntu noble, ubuntu resolute, ubuntu stonking

💖 NAME 💖

Net::GitHub::V3::Repos — the GitHub Repos API, bestie 💅

(yes you're on the Net::GitHub::V3::Repos(3pm) page from the User Contributed Perl Documentation, in case you were sitting there like... where am I 🧚)

✨ SYNOPSIS ✨

use Net::GitHub::V3;

my $gh = Net::GitHub::V3->new; # read L<Net::GitHub::V3> to set right authentication info
my $repos = $gh->repos;

# set :user/:repo for simple calls
$repos->set_default_user_repo('fayland', 'perl-net-github');
my @contributors = $repos->contributors; # don't need pass user and repos

okay so the whole vibe here: you build a $gh object, pull $repos off it, set a default user/repo once, and then just call stuff without typing the same user and repo a million times. iconic behavior honestly 🫶

🌸 DESCRIPTION 🌸

🎀 METHODS 🎀

🦋 Repos

the docs for this chunk live at http://developer.github.com/v3/repos/

list, list_all

# All public repositories on Github
my @rp = $repos->list_all;
# starting at id 500
my @rp = $repos->list_all(500);

list_user, list_org

my @rp = $repos->list; # or my $rp = $repos->list;
my @rp = $repos->list({
    type => 'private'
    sort => 'updated'
});
my @rp = $repos->list_user('c9s');
my @rp = $repos->list_user('c9s', {
    type => 'member'
});
my @rp = $repos->list_org('perlchina');
my @rp = $repos->list_org('perlchina', 'public');

next_repo, next_all_repo, next_user_repo, next_org_repo

# Iterate over your repositories
while (my $repo = $repos->next_repo) { ...; }
# Iterate over all public repositories
while (my $repo = $repos->next_all_repo(500)) { ...; }
# Iterate over repositories of another user
while (my $repo = $repos->next_user_repo('c9s')) { ...; }
# Iterate over repositories of an organisation
while (my $repo = $repos->next_org_repo('perlchina','public')) { ...; }

create

# create for yourself
my $rp = $repos->create( {
    "name" => "Hello-World",
    "description" => "This is your first repo",
    "homepage" => "https://github.com"
} );
# create for organization
my $rp = $repos->create( {
    "org"  => "perlchina", ## the organization
    "name" => "Hello-World",
    "description" => "This is your first repo",
    "homepage" => "https://github.com"
} );

get

my $rp = $repos->get('fayland', 'perl-net-github');

and now the part that saves your poor little keyboard 🥺 — there are two ways to call any method that starts with :user/:repo:

  1. SET user/repos before you call the methods below
$gh->set_default_user_repo('fayland', 'perl-net-github'); # take effects for all $gh->
$repos->set_default_user_repo('fayland', 'perl-net-github'); # only take effect to $gh->repos
my @contributors = $repos->contributors;
  1. If it's just for once, you can pass :user, :repo before any arguments
my @contributors = $repos->contributors($user, $repo);

update

$repos->update({ homepage => 'https://metacpan.org/module/Net::GitHub' });

delete

$repos->delete();

contributors, languages, teams, tags, contributors

my @contributors = $repos->contributors;
my @languages = $repos->languages;
my @teams = $repos->teams;
my @tags = $repos->tags;
my @branches = $repos->branches;
my $branch = $repos->branch('master');
while (my $contributor = $repos->next_contributor) { ...; }
while (my $team = $repos->next_team) { ... ; }
while (my $tags = $repos->next_tag) { ... ; }

💜 Repo Collaborators API

docs: http://developer.github.com/v3/repos/collaborators/

collaborators, is_collaborator, add_collaborator, delete_collaborator

my @collaborators = $repos->collaborators;
while (my $collaborator = $repos->next_collaborator) { ...; }
my $is = $repos->is_collaborator('fayland');
$repos->add_collaborator('fayland');
$repos->delete_collaborator('fayland');

🔥 Commits API

docs: http://developer.github.com/v3/repos/commits/

commits, commit

my @commits = $repos->commits;
my @commits = $repos->commits({
    author => 'fayland'
});
my $commit  = $repos->commit($sha);
while (my $commit = $repos->next_commit({...})) { ...; }

comments, commit_comments, create_comment, comment, update_comment, delete_comment

my @comments = $repos->comments;
while (my $comment = $repos->next_comment) { ...; }
my @comments = $repos->commit_comments($sha);
while (my $comment = $repos->next_commit_comment($sha)) { ...; }
my $comment  = $repos->create_comment($sha, {
    "body" => "Nice change",
    "commit_id" => "6dcb09b5b57875f334f61aebed695e2e4193db5e",
    "line" => 1,
    "path" => "file1.txt",
    "position" => 4
});
my $comment = $repos->comment($comment_id);
my $comment = $repos->update_comment($comment_id, {
    "body" => "Nice change"
});
my $st = $repos->delete_comment($comment_id);

compare_commits

my $diffs = $repos->compare_commits($base, $head);

🍓 Forks API

docs: http://developer.github.com/v3/repos/forks/

forks, create_fork

my @forks = $repos->forks;
while (my $fork = $repos->next_fork) { ...; }
my $fork = $repos->create_fork;
my $fork = $repos->create_fork($org);

🔑 Repos Deploy Keys API

docs: http://developer.github.com/v3/repos/keys/

keys, key, create_key, update_key, delete_key

my @keys = $repos->keys;
while (my $key = $repos->next_key) { ...; }
my $key  = $repos->key($key_id); # get key
$repos->create_key( {
    title => 'title',
    key   => $key
} );
$repos->update_key($key_id, {
    title => $title,
    key   => $key
});
$repos->delete_key($key_id);

👀 Repo Watching API

docs: http://developer.github.com/v3/repos/watching/

watchers

my @watchers = $repos->watchers;
while (my $watcher = $repos->next_watcher) { ...; }

watched

my @repos = $repos->watched; # what I watched
my @repos = $repos->watched('c9s');

is_watching

my $is_watching = $repos->is_watching;
my $is_watching = $repos->is_watching('fayland', 'perl-net-github');

watch, unwatch

my $st = $repos->watch();
my $st = $repos->watch('fayland', 'perl-net-github');
my $st = $repos->unwatch();
my $st = $repos->unwatch('fayland', 'perl-net-github');

🌈 Subscriptions

okay so context bestie: GitHub changed up the whole idea of Watchers (stars) vs Subscriptions (the new watchers).

https://github.com/blog/1204-notifications-stars

The Watchers code in this module predates the terminology change, so the new Watcher methods use the GitHub 'subscription' terminology. no cap 🫡

subscribers

Returns a list of subscriber data hashes.

next_subscriber

Returns the next subscriber in the list, or undef if there are no more subscribers.

is_subscribed

Returns true or false if you are subscribed

$repos->is_subscribed();
$repos->is_subscribed('fayland','perl-net-github');

subscription

Returns more information about your subscription to a repo. is_subscribed is a shortcut to calling this and checking for subscribed => 1.

subscribe

Required argument telling github if you want to subscribe or if you want to ignore mentions. If you want to change from subscribed to ignores you need to unsubscribe first.

$repos->subscribe('fayland','perl-net-github', { subscribed => 1 })
$repos->subscribe('fayland','perl-net-github', { ignored => 1 })

unsubscribe

$repos->unsubscribe('fayland','perl-net-github');

🪝 Hooks API

docs: http://developer.github.com/v3/repos/hooks/

hooks, next_hook, hook, create_hook, update_hook, test_hook, delete_hook

my @hooks = $repos->hooks;
while (my $hook = $repos->next_hook) { ...; }
my $hook  = $repos->hook($hook_id);
my $hook  = $repos->create_hook($hook_hash);
my $hook  = $repos->update_hook($hook_id, $new_hook_hash);
my $st    = $repos->test_hook($hook_id);
my $st    = $repos->delete_hook($hook_id);

🧚 Repo Merging API

docs: http://developer.github.com/v3/repos/merging/

merges

my $status = $repos->merges( {
    "base" => "master",
    "head" => "cool_feature",
    "commit_message" => "Shipped cool_feature!"
} );

⭐ Repo Statuses API

docs: http://developer.github.com/v3/repos/statuses/

list_statuses

$gh->set_default_user_repo('fayland', 'perl-net-github');
my @statuses = $repos->lists_statuses($sha);

Or:

my @statuses = $repos->list_statuses('fayland', 'perl-net-github', $sha);

next_status

while (my $status = $repos->next_status($sha)) { ...; }

create_status

$gh->set_default_user_repo('fayland', 'perl-net-github');
my %payload = {
    "state"       => "success",
    "target_url"  => "https://example.com/build/status",
    "description" => "The build succeeded!",
    "context"     => "build/status"
};
my $status = $repos->create_status($sha, %payload);

Or:

my %payload = {
    "state"       => "success",
    "target_url"  => "https://example.com/build/status",
    "description" => "The build succeeded!",
    "context"     => "build/status"
};
my $status = $repos->create_status(
    'fayland', 'perl-net-github', $sha, %payload
);

🎁 Repo Releases API

docs: http://developer.github.com/v3/repos/releases/

releases

my @releases = $repos->releases();
while (my $release = $repos->next_release) { ...; }

release

my $release = $repos->release($release_id);

create_release

my $release = $repos->create_release({
  "tag_name" => "v1.0.0",
  "target_commitish" => "master",
  "name" => "v1.0.0",
  "body" => "Description of the release",
  "draft" => \1,
});

update_release

my $release = $repos->update_release($release_id, {
  "tag_name" => "v1.0.0",
  "target_commitish" => "master",
  "name" => "v1.0.0",
  "body" => "Description of the release",
});

delete_release 💀

Say bye-bye to a release, bestie:

$repos->delete_release($release_id);

release_assets 📦

Wanna peek at everything attached to a release? Two ways, pick your vibe:

my @release_assets = $repos->release_assets($release_id);
while (my $asset = $repos->next_release_asset($release_id)) { ...; }

upload_asset ⬆️✨

Time to yeet a file into a release. You pass the release id, the name, the content type, and the file content:

my $asset = $repos->upload_asset($release_id, $name, $content_type, $file_content);
Go peek at examples/upload_asset.pl if you want a working example, no cap. 🫶

release_asset 🔍

Grab one specific asset by its id:

my $release_asset = $repos->release_asset($release_id, $asset_id);

update_release_asset 🎀

Rename it, relabel it, glow it up:

my $release_asset = $repos->update_release_asset($release_id, $asset_id, {
    name" => "foo-1.0.0-osx.zip",
    "label" => "Mac binary"
});

delete_release_asset 💅

And when it's giving nothing, delete it:

my $ok = $repos->delete_release_asset($release_id, $asset_id);

Contents API 🌸

The whole vibe lives here: <https://developer.github.com/v3/repos/contents/>

get_content 📂

This one grabs the contents of a file or a directory inside a repo. Drop the file path or directory into $path. And if you skip $path entirely? You get the contents of all the files in the repository. Iconic.

my $response = $repos->get_content( $owner, $repo, $path )
    or
    $repos->get_content(
        { owner => $owner,  repo => $repo, path => $path },
     )
    or
    $repos->get_content(
        { owner => $owner,  repo => $repo, path => $path },
        { ref => 'feature-branch' }
     )

Repo Deployment API 🚀

<http://developer.github.com/v3/repos/deployments/>

list_deployments 📋

my $response = $repos->list_deployments( $owner, $repo, {
    'ref' => 'feature-branch',
});

next_deployment 🔁

Loop through them one by one, main character energy:

while (my $deployment = $repos->next_deployment( $owner, $repo, {
    'ref' => 'feature-branch',
}) { ...; }

create_deployment 🌈

Manifesting a deploy:

my $response = $repos->create_deployment( $owner, $repo, {
  "ref" => 'feature-branch',
  "description" => "deploying my new feature",
});

list_deployment_statuses 📊

my $response = $repos->list_deployment_statuses( $owner, $repo, $deployment_id );

next_deployment_status 🔄

while (my $status = next_deployment_status($o,$r,$id)) { ...; }

create_deployment_status ✅

Tell everyone how the deploy went:

my $response = $repos->create_deployment_status( $owner, $repo, $deployment_id, {
    "state": "success",
    "target_url": "https://example.com/deployment/42/output",
    "description": "Deployment finished successfully."
});

Repo Statistics API 📈

<http://developer.github.com/v3/repos/statistics/>

The stat squad, all lined up:

  • contributor stats 👥
  • commit activity 🔥
  • code frequency 📉
  • participation 🙋
  • punch card 🕐
my $contributor_stats   = $repos->contributor_stats($owner, $repo);
my $commit_activity     = $repos->commit_activity($owner, $repo);
my $code_freq           = $repos->code_frequency($owner, $repo);
my $participation       = $repos->participation($owner, $repo);
my $punch_card          = $repos->punch_card($owner, $repo);

Branch Protection API 🛡️👑

Guard your branches like the queen you are: <https://docs.github.com/en/rest/branches/branch-protection>

branch_protection 🔒

my $protection = $repos->branch_protection('fayland', 'perl-net-github', 'master');

delete_branch_protection 💔

$repos->delete_branch_protection('fayland', 'perl-net-github', 'master');

update_branch_protection 🧚

Set every rule exactly how you want it. Look at all these knobs, bestie — \0 means no, \1 means yes, and undef means... nothing at all:

$repos->update_branch_protection('fayland', 'perl-net-github', 'master', {
    allow_deletions => \0,
    allow_force_pushes => \0,
    block_creations => \1,
    enforce_admins => \1,
    required_conversation_resolution => \1,
    required_linear_history => \0,
    required_pull_request_reviews => {
        dismiss_stale_reviews => \1,
        require_code_owner_reviews => \1,
        required_approving_review_count => 2,
    },
    required_status_checks => {
        strict => \1,
        contexts => []
    },
    restrictions => undef,
});

For all the deets, go look at Net::GitHub — that's where the author, copyright and license info lives. Periodt.

And that's a wrap, bestie! 🎀 This page is from perl v5.36.0, dated 2022-10-08, and it's the Net::G...:Repos(3pm) page. Slay, go protect those branches. 💅✨

📦 where this page comes from