Scroll to navigation

Net::GitHub::V3::Repos(3pm) User Contributed Perl Documentation Net::GitHub::V3::Repos(3pm)

NAME

Net::GitHub::V3::Repos - GitHub Repos API

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

DESCRIPTION

METHODS

Repos

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

    # All public repositories on Github
    my @rp = $repos->list_all;
    # starting at id 500
    my @rp = $repos->list_all(500);
    
    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');
    
    # 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 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"
    } );
    
    my $rp = $repos->get('fayland', 'perl-net-github');

To ease the keyboard, we provied two ways to call any method which starts with :user/:repo

1. SET user/repos before call 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;

2. If it is just for once, we can pass :user, :repo before any arguments

    my @contributors = $repos->contributors($user, $repo);

    $repos->update({ homepage => 'https://metacpan.org/module/Net::GitHub' });
    
    $repos->delete();
    
    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

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

    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

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

    my @commits = $repos->commits;
    my @commits = $repos->commits({
        author => 'fayland'
    });
    my $commit  = $repos->commit($sha);
    while (my $commit = $repos->next_commit({...})) { ...; }
    
    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);
    
    my $diffs = $repos->compare_commits($base, $head);

Forks API

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

    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

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

    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

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

    my @watchers = $repos->watchers;
    while (my $watcher = $repos->next_watcher) { ...; }
    
    my @repos = $repos->watched; # what I watched
    my @repos = $repos->watched('c9s');
    
    my $is_watching = $repos->is_watching;
    my $is_watching = $repos->is_watching('fayland', 'perl-net-github');
    
    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

Github changed the ideas of Watchers (stars) and Subscriptions (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.

Returns a list of subscriber data hashes.
Returns the next subscriber in the list, or undef if there are no more subscribers.
Returns true or false if you are subscribed 

    $repos->is_subscribed();
    $repos->is_subscribed('fayland','perl-net-github');
Returns more information about your subscription to a repo. is_subscribed is a shortcut to calling this and checking for subscribed => 1.
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 })
    
    $repos->unsubscribe('fayland','perl-net-github');

Hooks API

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

    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

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

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

Repo Statuses API

<http://developer.github.com/v3/repos/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);
    
    while (my $status = $repos->next_status($sha)) { ...; }
    
    $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

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

    my @releases = $repos->releases();
    while (my $release = $repos->next_release) { ...; }
    
    my $release = $repos->release($release_id);
    
    my $release = $repos->create_release({
      "tag_name" => "v1.0.0",
      "target_commitish" => "master",
      "name" => "v1.0.0",
      "body" => "Description of the release",
      "draft" => \1,
    });
    
    my $release = $repos->update_release($release_id, {
      "tag_name" => "v1.0.0",
      "target_commitish" => "master",
      "name" => "v1.0.0",
      "body" => "Description of the release",
    });
    
    $repos->delete_release($release_id);
    
    my @release_assets = $repos->release_assets($release_id);
    while (my $asset = $repos->next_release_asset($release_id)) { ...; }
    
    my $asset = $repos->upload_asset($release_id, $name, $content_type, $file_content);

Check examples/upload_asset.pl for a working example.

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

Contents API

<https://developer.github.com/v3/repos/contents/>

Gets the contents of a file or directory in a repository. Specify the file path or directory in $path. If you omit $path, you will receive the contents of all files in the repository. 

    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/>

    my $response = $repos->list_deployments( $owner, $repo, {
        'ref' => 'feature-branch',
    });
    
    while (my $deployment = $repos->next_deployment( $owner, $repo, {
        'ref' => 'feature-branch',
    }) { ...; }
    
    my $response = $repos->create_deployment( $owner, $repo, {
      "ref" => 'feature-branch',
      "description" => "deploying my new feature",
    });
    
    my $response = $repos->list_deployment_statuses( $owner, $repo, $deployment_id );
    
    while (my $status = next_deployment_status($o,$r,$id)) { ...; }
    
    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/>

commit activity
    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

<https://docs.github.com/en/rest/branches/branch-protection>

    my $protection = $repos->branch_protection('fayland', 'perl-net-github', 'master');
    
    $repos->delete_branch_protection('fayland', 'perl-net-github', 'master');
    
    $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,
    });

AUTHOR & COPYRIGHT & LICENSE

Refer Net::GitHub

2022-10-08 perl v5.34.0