Commit 8cf66d7f authored by Roman Lacko's avatar Roman Lacko
Browse files

Initial commit (v8.12.1)

parents
package GitLab;
use strict;
use warnings;
use Log::Any qw($log);
use Carp;
use GitLab::API;
use GitLab::Groups;
use GitLab::Namespaces;
use GitLab::Users;
use Try::Tiny;
use parent "Exporter";
our @EXPORT_OK = ();
our %EXPORT_TAGS = (
group_visibility => [ qw|GROUP_VISIBILITY GROUP_PRIVATE GROUP_INTERNAL GROUP_PUBLIC | ],
member_access => [ qw|MEMBER_ACCESS MEMBER_GUEST MEMBER_REPORTER MEMBER_DEVELOPER MEMBER_MASTER MEMBER_OWNER | ],
utils => [ qw|group_visibility_name member_access_name| ],
);
Exporter::export_ok_tags(qw|group_visibility member_access utils|);
#===============================================================================
# Constants
#===============================================================================
use constant {
# Group Visibility
GROUP_PRIVATE => 00,
GROUP_INTERNAL => 10,
GROUP_PUBLIC => 20,
# Member rights
MEMBER_GUEST => 10,
MEMBER_REPORTER => 20,
MEMBER_DEVELOPER => 30,
MEMBER_MASTER => 40,
MEMBER_OWNER => 50,
};
use constant GROUP_VISIBILITY
=> (GROUP_PRIVATE, GROUP_INTERNAL, GROUP_PUBLIC);
use constant MEMBER_ACCESS
=> (MEMBER_GUEST, MEMBER_REPORTER, MEMBER_DEVELOPER, MEMBER_MASTER, MEMBER_OWNER);
#===============================================================================
# Utilities
#===============================================================================
my %group_visibility_map = (
"10" => "Private",
"20" => "Internal",
"30" => "Public",
);
sub group_visibility_name {
my ($code) = @_;
return $group_visibility_map{$code} // "Invalid";
}
my %member_access_map = (
"10" => "Guest",
"20" => "Reporter",
"30" => "Developer",
"40" => "Master",
"50" => "Owner",
);
sub member_access_name {
my ($code) = @_;
return $member_access_map{$code} // "Invalid";
}
1;
__END__
=head1 NAME
GitLab - convenience wrapper for GitLab::API that provides useful constants
=head1 SYNOPSIS
use GitLab qw(:utils);
my $gitlab = GitLab::API->new(...);
my $users = $gitlab->users();
=head1 DESCRIPTION
=head2 Constants
The module defines access level constants. See appropriate API documentation
for explanation.
=head3 Group visibility
Import with C<:group_visibility> tag.
10 GROUP_PRIVATE
20 GROUP_INTERNAL
30 GROUP_PUBLIC
=head3 Member access
Import with C<:member_access> tag.
10 MEMBER_GUEST
20 MEMBER_REPORTER
30 MEMBER_DEVELOPER
40 MEMBER_MASTER
50 MEMBER_OWNER
=head2 Utilities
Import with C<:utils> tag.
=over
=item group_visibility_name()
$name = GitLab::group_visibility_name($code)
Translates a Group Visibility code to its string representation, i.e. I<Private>, I<Internal> or I<Public>.
If the parameter does not represent a valid GitLab Group Visibility code, returns I<Invalid>.
=item member_access_name()
$name = GitLab::member_access_name($code);
Translates a Member Access code to its string representation, i.e. I<Guest>, I<Reporter>, I<Developer>, I<Master> and I<Owner>.
If the parameter does not represent a valid GitLab Member Access code, returns I<Invalid>.
=back
=head1 AUTHOR
Roman Lacko <L<xlacko1@fi.muni.cz>>
=head1 SEE ALSO
=over
=item L<GitLab::API::v3>
Complete GitLab API v3 implementation with CLI support.
=item L<GitLab::API>
implementation of the L<GitLab API|http://docs.gitlab.com/ce/api/> client.
=item L<GitLab::Groups>
L<GitLab Groups|http://docs.gitlab.com/ce/api/groups.html> methods.
=item L<GitLab::Namespaces>
L<GitLab Namespaces|http://docs.gitlab.com/ce/api/namespaces.html> methods.
=item L<GitLab::Users>
L<GitLab Users|http://docs.gitlab.com/ce/api/users.html> methods.
=back
This diff is collapsed.
package GitLab::Groups;
use utf8;
use strict;
use warnings;
use vars qw($VERSION);
use GitLab::API;
use Log::Any qw($log);
our $VERSION = v8.12.1;
my $requests = {
groups => {
method => "GET",
path => "/groups",
query => [ qw(search) ],
paginated => 1,
},
group_get_projects => {
method => "GET",
path => "/groups/<gid>/projects",
optional => [ qw(archived visibility order_by sort search ci_enabled_first) ],
paginated => 1,
},
group_details => {
method => "GET",
path => "/groups/<gid>",
},
group_create => {
method => "POST",
path => "/groups",
required => [ qw(name path) ],
optional => [ qw(description visibility_level lfs_enabled request_access_enabled) ],
},
transfer_project_to_group => {
method => "POST",
path => "/groups/<gid>/projects/<projid>",
},
group_update => {
method => "PUT",
path => "/groups/<gid>",
optional => [ qw(name path description visibility_level lfs_enabled request_access_enabled) ],
},
group_delete => {
method => "DELETE",
path => "/groups/<gid>",
},
group_members => {
method => "GET",
path => "/groups/<gid>/members",
paginated => 1,
},
group_add_member => {
method => "POST",
path => "/groups/<gid>/members",
required => [ qw!user_id access_level! ],
},
group_update_member => {
method => "PUT",
path => "/groups/<gid>/members/<user_id>",
required => [ qw!access_level! ],
},
group_delete_member => {
method => "DELETE",
path => "/groups/<gid>/members/<user_id>",
},
};
sub import {
$log->debug("initializing " . __PACKAGE__);
while (my ($name, $tmpl) = each(%$requests)) {
$tmpl->{name} = $name unless exists $tmpl->{name};
GitLab::API->register($tmpl);
}
}
1;
__END__
=head1 NAME
GitLab::Groups - implements group API calls
See L<GitLab API -- Groups|http://doc.gitlab.com/ce/api/groups.html> for details and
response formats.
=head1 VERSION
Implements API calls for GitLab CE C<v8.10.0>.
Checked 2016-09-29 for GitLab CE C<v8.12.1>.
=head1 DESCRIPTION
=head2 Notation
Please see the documentation for the L<GitLab::Users> module.
Note that not all optional arguments are listed.
Please refer to the official documentation for the full list.
=head2 Group CRUD operations
=over
=item groups()
$groups = $gitlab->groups( [:search] );
Returns a list of groups.
An optional parameter C<search> can be used to filter the list by substring match on C<name>.
=item group_details()
$details = $gitlab->group_details( :gid );
Returns details about a group with the given C<gid>.
=item group_create()
$group = $gitlab->group_create( :name, :path, [:description], [:visibility_level] );
Creates a new group. Required arguments are
name the name of the group,
path the path for the group (must be unique)
In addition, the following I<optional> arguments can be specified:
description group's description
visibility_level see GitLab::API for possible values
=item group_update()
$group = $gitlab->group_update( :gid );
Updates the grup with the given C<gid>.
Takes same arguments as C<group_create>, except they are all optional.
=item group_delete()
$gitlab->group_delete( :gid );
Deletes the group with the given C<gid>.
=back
=head2 Group members
=over
=item group_members()
$members = $gitlab->group_members( :gid );
Returns a list of members in the grup with the specified C<gid>.
=item group_add_member()
$gitlab->group_add_member( :gid, :user_id, :access_level );
Adds a user with C<user_id> to the group with the given C<gid> with the specified C<access_level>.
See L<GitLab::API> module for possible access level values.
=item group_update_member()
$gitlab->group_update_member( :gid, :user_id, :access_level );
For user with the given C<user_id> the function changes his C<access_level> in the group with the specified C<gid>.
=item group_delete_member()
$gitlab->group_delete_member( :gid, :user_id );
Removes the user with C<user_id> from the group with the specified C<gid>.
=back
=head2 Group projects and transfer
=over
=item group_get_projects()
$projects = $gitlab->group_get_projects( :gid );
Returns a list of projects owned by the group with the given C<gid>.
=item transfer_project_to_group()
$gitlab->transfer_project_to_group( :gid, :projid );
Moves the project with C<projid> to the namespace of the group with the given C<gid>.
I<This method is available only for administrators.>
=back
=head1 AUTHOR
Roman Lacko <L<xlacko1@fi.muni.cz>>
=head1 SEE ALSO
=over
=item L<GitLab>
Wrapper around L<GitLab::API> and other C<GitLab::*> modules.
=back
package GitLab::Namespaces;
use utf8;
use strict;
use warnings;
use vars qw($VERSION);
use GitLab::API;
use Log::Any qw($log);
our $VERSION = v8.12.1;
my $requests = {
namespaces => {
method => "GET",
path => "/namespaces",
query => [ qw(search) ],
paginated => 1,
}
};
sub import {
$log->debug("initializing " . __PACKAGE__);
while (my ($name, $tmpl) = each(%$requests)) {
$tmpl->{name} = $name unless exists $tmpl->{name};
GitLab::API->register($tmpl);
}
}
1;
__END__
=head1 NAME
GitLab::Namespaces - extension for Namespaces API
See L<GitLab API -- Namespaces|http://doc.gitlab.com/ce/api/namespaces.html> for details and response formats.
=head1 SYNOPSIS
use GitLab::API;
use GitLab::Namespaces;
my $api = GitLab::API->new();
# get namespaces exposed to user john.doe
$api->sudo("john.doe");
my $namespaces = $api->namespaces(search => "group1");
=head1 VERSION
Implements API calls for GitLab CE C<v8.10.0>.
Checked 2016-09-29 for GitLab CE C<v8.12.1>.
=head1 DESCRIPTION
From GitLab API: I<"Usernames and groupnames fall under a special category called namespaces.">
=over
=item namespaces()
$namespaces = $gitlab->namespaces();
$namespaces = $gitlab->namespaces(search => $what);
Returns all namespaces for currently authenticated user.
If an optional argument C<search> is used, only those namespaces that contain the requested string are returned.
To get namespaces of user with login C<$login>, you can do this:
$gitlab->sudo($login);
$namespaces = $gitlab->namespaces();
Note that the authenticated user must be an administrator to use L<GitLab::API/sudo>.
If the user with login C<$login> is an administrator, the call will return B<all> namespaces.
=back
=head1 AUTHOR
Roman Lacko <L<xlacko1@fi.muni.cz>>
=head1 SEE ALSO
=over
=item L<GitLab>
Wrapper around L<GitLab::API> and other C<GitLab::*> modules.
=back
package GitLab::Users;
use utf8;
use strict;
use warnings;
use vars qw($VERSION);
use GitLab::API;
use Log::Any qw($log);
our $VERSION = 8.12.1;
my $requests = {
users => {
method => "GET",
path => "/users",
query => [ qw(username search) ],
paginated => 1,
},
user_by_id => {
method => "GET",
path => "/users/<uid>",
},
user_create => {
method => "POST",
path => "/users",
required => [ qw(email password username name) ],
optional => [ qw(skype linkedin twitter website_url projects_limit
extern_uid provider bio location admin confirm can_create_group external) ],
},
user_update => {
method => "PUT",
path => "/users/<uid>",
# update can cause Conflict, but API always returns 404
ret => { 404 => "Not found or Conflict" },
optional => [ qw(email password name username skype linkedin twitter
website_url projects_limit extern_uid provider bio location admin can_create_group external) ],
},
user_delete => {
method => "DELETE",
path => "/users/<uid>",
},
user => {
method => "GET",
path => "/user",
},
self_ssh_keys => {
method => "GET",
path => "/user/keys",
paginated => 1,
},
self_get_ssh_key => {
method => "GET",
path => "/user/keys/<keyid>",
},
user_get_ssh_keys => {
method => "GET",
path => "/users/<uid>/keys",
paginated => 1,
},
self_add_ssh_key => {
method => "POST",
path => "/user/keys",
required => [ qw!title key! ],
},
user_add_ssh_key => {
method => "POST",
path => "/users/<uid>/keys",
required => [ qw!title key! ],
},
self_delete_ssh_key => {
method => "DELETE",
path => "/user/keys/<keyid>",
},
user_delete_ssh_key => {
method => "DELETE",
path => "/users/<uid>/keys/<keyid>",
},
self_get_emails => {
method => "GET",
path => "/user/emails",
paginated => 1,
},
user_get_emails => {
method => "GET",
path => "/users/<uid>/emails",
paginated => 1,
},
self_get_email => {
method => "GET",
path => "/user/emails/<eid>",
},
# not officially supported, may not work :(
# user_get_email => {
#  method => "GET",
#  path => "/users/<uid>/emails/<eid>",
# },
self_add_email => {
method => "POST",
path => "/user/emails",
required => [ qw!email! ],
},
user_add_email => {
method => "POST",
path => "/users/<uid>/emails",
required => [ qw!email! ],
},
self_delete_email => {
method => "DELETE",
path => "/user/emails/<eid>",
},
user_delete_email => {
method => "DELETE",
path => "/users/<uid>/emails/<eid>",
},
user_block => {
method => "PUT",
path => "/users/<uid>/block",
},
user_unblock => {
method => "PUT",
path => "/users/<uid>/unblock",
},
};
sub import {
$log->debug("initializing " . __PACKAGE__);
while (my ($name, $tmpl) = each(%$requests)) {
$tmpl->{name} = $name unless exists $tmpl->{name};
GitLab::API->register($tmpl);
}
}
1;
__END__
=head1 NAME