|
|
# NAME
|
|
|
|
|
|
`GitLab::Users` - implements user API calls
|
|
|
|
|
|
See [GitLab API -- Users](http://doc.gitlab.com/ce/api/users.html) for details and
|
|
|
response formats.
|
|
|
|
|
|
# VERSION
|
|
|
|
|
|
Implements API calls for GitLab CE `v8.10.0`.
|
|
|
Checked 2016-09-29 for GitLab CE `v8.12.1`.
|
|
|
|
|
|
# SYNOPSIS
|
|
|
|
|
|
```{.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 $john = $api->users(username => "john_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](pod-GitLab-API.md#exec_request), but to simplify the documentation,
|
|
|
we will use the following notation:
|
|
|
|
|
|
```{.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
|
|
|
|
|
|
```{.pl}
|
|
|
$gitlab->users(search => "john_doe");
|
|
|
```
|
|
|
|
|
|
Optional arguments are denoted as ` [:username] `.
|
|
|
Note that not all optional arguments are listed.
|
|
|
Please refer to the official documentation for the full list.
|
|
|
|
|
|
## User CRUD operations
|
|
|
|
|
|
- `users()`
|
|
|
|
|
|
```{.pl}
|
|
|
$users = $gitlab->users( [:username], [:search] );
|
|
|
```
|
|
|
|
|
|
This method returns all users. The optional arguments can be used
|
|
|
to filter out the results:
|
|
|
|
|
|
| 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()`
|
|
|
|
|
|
```{.pl}
|
|
|
$user = $gitlab->user_by_id( :uid );
|
|
|
```
|
|
|
|
|
|
Returns a user with the given `uid`.
|
|
|
|
|
|
- `user_create()`
|
|
|
|
|
|
```{.pl}
|
|
|
$user = $gitlab->user_create( :email, :password, :username, :name [, ...]);
|
|
|
```
|
|
|
|
|
|
Creates a new user and if succeeds, returns the generated account information.
|
|
|
|
|
|
| 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:
|
|
|
|
|
|
| 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()`
|
|
|
|
|
|
```{.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
|
|
|
and username, it is probably not a very sane thing to do.
|
|
|
|
|
|
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.
|
|
|
|
|
|
- `user_delete()`
|
|
|
|
|
|
```{.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.
|
|
|
|
|
|
(from the GitLab API documentation).
|
|
|
|
|
|
- `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.
|
|
|
|
|
|
## SSH keys
|
|
|
|
|
|
- `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()`
|
|
|
|
|
|
```{.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()`
|
|
|
|
|
|
```{.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()`
|
|
|
|
|
|
```{.pl}
|
|
|
$key = $gitlab->self_add_ssh_key( :title, :key );
|
|
|
```
|
|
|
|
|
|
Adds a new key for the user that makes the request. Required arguments are
|
|
|
|
|
|
| argument | description |
|
|
|
| -------- | ----------- |
|
|
|
| `title` | the title of the key |
|
|
|
| `key` | public SSH key |
|
|
|
|
|
|
- `user_add_ssh_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()`
|
|
|
|
|
|
```{.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()`
|
|
|
|
|
|
```{.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()`
|
|
|
|
|
|
```{.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()`
|
|
|
|
|
|
```{.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()`
|
|
|
|
|
|
```{.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()`
|
|
|
|
|
|
```{.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()`
|
|
|
|
|
|
```{.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()`
|
|
|
|
|
|
```{.pl}
|
|
|
$gitlab->self_delete_email( :eid );
|
|
|
```
|
|
|
|
|
|
Deletes the e-mail with `eid` of the user that makes the request.
|
|
|
|
|
|
- `user_delete_email()`
|
|
|
|
|
|
```{.pl}
|
|
|
$gitlab->user_delete_email( :uid, :eid );
|
|
|
```
|
|
|
|
|
|
Removes the e-mail with `eid` of the user with the given `uid`.
|
|
|
|
|
|
## Account blocking
|
|
|
|
|
|
- `user_block()`
|
|
|
|
|
|
```{.pl}
|
|
|
$gitlab->user_block( :uid );
|
|
|
```
|
|
|
|
|
|
Blocks the user with `uid` in the GitLab.
|
|
|
|
|
|
- `user_unblock()`
|
|
|
|
|
|
```{.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`](mailto:xlacko1@fi.muni.cz)>
|
|
|
|
|
|
# SEE ALSO
|
|
|
|
|
|
- [GitLab](pod-GitLab.md)
|
|
|
|
|
|
Wrapper around [GitLab::API](pod-GitLab-API.md) and other `GitLab::*` modules. |