Commit 5090dd03 authored by Roman Lacko's avatar Roman Lacko
Browse files

Update pod-GitLab-Users.md

parent 21c47855
# NAME
GitLab::Users - implements user API calls
`GitLab::Users` - implements user API calls
See [GitLab API -- Users](http://doc.gitlab.com/ce/api/users.html) for details and
response formats.
......@@ -12,35 +12,41 @@ Checked 2016-09-29 for GitLab CE `v8.12.1`.
# SYNOPSIS
use GitLab::API;
use GitLab::Users;
# all calls from GitLab::Users are "injected" into the GitLab::API as methods
```{.pl}
use GitLab::API;
use GitLab::Users;
# all calls from GitLab::Users are "injected" into the GitLab::API as methods
my $api = GitLab::API->new();
my $api = GitLab::API->new(...);
my $john = $api->users(username => "john_doe");
my $john = $api->users(username => "john_doe");
$api->user_create(
email => "jane34@somewhere.com",
password => "s3cre1",
username => "jane.doe",
name => "Jane Doe"
);
$api->user_create(
email => "jane34@somewhere.com",
password => "s3cre1",
username => "jane.doe",
name => "Jane Doe"
);
```
# DESCRIPTION
## Notation
All methods take a hash of arguments as specified in the documentation for
["exec\_request" in GitLab::API](https://metacpan.org/pod/GitLab::API#exec_request), but to simplify the documentation,
[`exec_request` in GitLab::API](pod-GitLab-API.md#exec_request), but to simplify the documentation,
we will use the following notation:
users( :username, :search )
```{.rb}
users( :username, :search )
```
which means that the `users` method takes a hash with two keys, `username`
and `search`, so it can be called as
$gitlab->users(search => "john_doe");
```{.pl}
$gitlab->users(search => "john_doe");
```
Optional arguments are denoted as ` [:username] `.
Note that not all optional arguments are listed.
......@@ -48,47 +54,61 @@ Please refer to the official documentation for the full list.
## User CRUD operations
- users()
- `users()`
$users = $gitlab->users( [:username], [:search] );
```{.pl}
$users = $gitlab->users( [:username], [:search] );
```
This method returns all users. The optional arguments can be used
to filter out the results:
username search for a user by his username (exact match)
search search for users with username or email (substring match)
| argument | description |
| ------------- | ----------- |
| `username` | search for a user by his username (**exact match**) |
| `search` | search for users with username or email (**substring match**) |
Note that the returned value is still an array even when `users(username => $username)`
always returns at most one result.
- user\_by\_id()
- `user_by_id()`
$user = $gitlab->user_by_id( :uid );
```{.pl}
$user = $gitlab->user_by_id( :uid );
```
Returns a user with the given `uid`.
- user\_create()
- `user_create()`
$user = $gitlab->user_create( :email, :password, :username, :name );
```{.pl}
$user = $gitlab->user_create( :email, :password, :username, :name [, ...]);
```
Creates a new user and if succeeds, returns the generated account information.
email primary email, must not exist in GitLab,
password user password,
username login, must not exist in GitLab,
name display name
| argument | description |
| ------------------- | ----------- |
| `email` | primary email, must not exist in GitLab |
| `password` | user password |
| `username` | login, must not exist in GitLab |
| `name` | display name |
The function can take many optional arguments. Please see the API documentation for
the full list. Most interesting arguments are:
admin create an admin account (bool)
can_create_group the user will be able to create group (bool)
external create an external account (bool)
projects_limit maximum number of projects the user can own
| argument | description |
| -------- | ----------- |
| `admin` | create an admin account (bool) |
| `can_create_group` | the user will be able to create group (bool) |
| `external` | create an external account (bool) |
| `projects_limit` | maximum number of projects the user can own |
- user\_update()
- `user_update()`
$user = $gitlab->user_update( :uid );
```{.pl}
$user = $gitlab->user_update( :uid );
```
Updates the user with the given `uid`. It takes the same arguments as `user_create`
except they are all optional. Note that though it is possible to change user's primary e-mail
......@@ -96,150 +116,189 @@ Please refer to the official documentation for the full list.
Also, from documentation:
Note, at the moment this method does only return a 404 error, even in cases where
a 409 (Conflict) would be more appropriate, e.g. when renaming the email address to some existing one.
> Note, at the moment this method does only return a 404 error, even in cases where
> a 409 (Conflict) would be more appropriate, e.g. when renaming the email address to some existing one.
- user\_delete()
- `user_delete()`
$gitlab->user_delete( :uid );
```{.pl}
$gitlab->user_delete( :uid );
```
Deletes the user with the given `uid`.
Note that
calling this function for a non-existent user id still returns a status code 200 OK.
The JSON response differs if the user was actually deleted or not.
> calling this function for a non-existent user id still returns a status code 200 OK.
> The JSON response differs if the user was actually deleted or not.
(from the GitLab API documentation).
- user()
- `user()`
$user = $gitlab->user();
```{.pl}
$user = $gitlab->user();
```
Returns the user whose authentication key is used for the request
(or impersonated user if `sudo` is in effect).
Behaves the same as the ["whoami" in GitLab::API](https://metacpan.org/pod/GitLab::API#whoami) method.
Behaves the same as the [`whoami` in GitLab::API](https://metacpan.org/pod/GitLab::API#whoami) method.
## SSH keys
- self\_ssh\_keys()
- `self_ssh_keys()`
$keys = $gitlab->self_ssh_keys();
```{.pl}
$keys = $gitlab->self_ssh_keys();
```
Returns a list of SSH keys for the user that makes the request.
- self\_get\_ssh\_key()
- `self_get_ssh_key()`
$key = $gitlab->self_get_ssh_key( :keyid );
```{.pl}
$key = $gitlab->self_get_ssh_key( :keyid );
```
For the user that makes the request, the function returns the SSH key with the given `keyid`.
- user\_get\_ssh\_keys()
- `user_get_ssh_keys()`
$keys = $gitlab->user_get_ssh_keys( :uid );
```{.pl}
$keys = $gitlab->user_get_ssh_keys( :uid );
```
Returns a list of SSH keys for the user with the given `uid`.
- self\_add\_ssh\_key()
- `self_add_ssh_key()`
$key = $gitlab->self_add_ssh_key( :title, :key );
```{.pl}
$key = $gitlab->self_add_ssh_key( :title, :key );
```
Adds a new key for the user that makes the request. Required arguments are
title the title of the key
key public SSH key
| argument | description |
| -------- | ----------- |
| `title` | the title of the key |
| `key` | public SSH key |
- user\_add\_ssh\_key()
- `user_add_ssh_key()`
$key = $gitlab->user_add_ssh_key( :uid, :title, :key );
```{.pl}
$key = $gitlab->user_add_ssh_key( :uid, :title, :key );
```
Similar to `self_add_ssh_key`, but targets the user with the given `uid`.
- self\_delete\_ssh\_key()
- `self_delete_ssh_key()`
$gitlab->self_delete_ssh_key( :keyid )
```{.pl}
$gitlab->self_delete_ssh_key( :keyid )
```
Removes the SSH key with the given `keyid` for the user that makes the request.
- user\_delete\_ssh\_key()
- `user_delete_ssh_key()`
$gitlab->user_delete_ssh_key( :uid, :keyid );
```{.pl}
$gitlab->user_delete_ssh_key( :uid, :keyid );
```
Removes the SSH key with the `keyid` for the user with the given `uid`.
## E-mails
- self\_get\_emails()
- `self_get_emails()`
$emails = $gitlab->self_get_emails();
```{.pl}
$emails = $gitlab->self_get_emails();
```
Returns a list of **secondary** e-mails for the user that makes the request.
Note that primary e-mail can be obtained from the result of `whoami`.
- user\_get\_emails()
- `user_get_emails()`
$emails = $gitlab->user_get_emails( :uid );
```{.pl}
$emails = $gitlab->user_get_emails( :uid );
```
Returns a list of **secondary** e-mails for the user with the `uid`.
Note that primary e-mail can be obtained from the result of `user_by_id`.
- self\_get\_email()
- `self_get_email()`
$email = $gitlab->self_get_email( :eid );
```{.pl}
$email = $gitlab->self_get_email( :eid );
```
Returns the e-mail with the given `eid` of the user that makes the request.
- self\_add\_email()
- `self_add_email()`
$email = $gitlab->self_add_email( :email );
```{.pl}
$email = $gitlab->self_add_email( :email );
```
Adds a new `email` for the user that makes the request. The e-mail must
not exist in GitLab.
- user\_add\_email()
- `user_add_email()`
$email = $gitlab->user_add_email( :uid, :email );
```{.pl}
$email = $gitlab->user_add_email( :uid, :email );
```
Adds a new `email` for the user with the given `uid`. The e-mail must
not exist in GitLab.
- self\_delete\_email()
- `self_delete_email()`
$gitlab->self_delete_email( :eid );
```{.pl}
$gitlab->self_delete_email( :eid );
```
Deletes the e-mail with `eid` of the user that makes the request.
- user\_delete\_email()
- `user_delete_email()`
$gitlab->user_delete_email( :uid, :eid );
```{.pl}
$gitlab->user_delete_email( :uid, :eid );
```
Removes the e-mail with `eid` of the user with the given `uid`.
## Account blocking
- user\_block()
- `user_block()`
$gitlab->user_block( :uid );
```{.pl}
$gitlab->user_block( :uid );
```
Blocks the user with `uid` in the GitLab.
- user\_unblock()
- `user_unblock()`
$gitlab->user_unblock( :uid );
```{.pl}
$gitlab->user_unblock( :uid );
```
Unblocks the user with `uid` in the GitLab.
Note that LDAP blocked users cannot be unblocked by this function.
In that case the API would return `403 Forbidden`.
# AUTHOR
Roman Lacko <[xlacko1@fi.muni.cz](https://metacpan.org/pod/xlacko1@fi.muni.cz)>
Roman Lacko <[`xlacko1@fi.muni.cz`](mailto:xlacko1@fi.muni.cz)>
# SEE ALSO
- [GitLab](https://metacpan.org/pod/GitLab)
- [GitLab](pod-GitLab.md)
Wrapper around [GitLab::API](https://metacpan.org/pod/GitLab::API) and other `GitLab::*` modules.
Wrapper around [GitLab::API](pod-GitLab-API.md) and other `GitLab::*` modules.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment