Merge branch 'master' into docs-patch-71docs-patch-71

1 files changed, 175 insertions, 67 deletions

diff --git a/doc/api/users.md b/doc/api/users.md
index 47028c679b8..b41fd106fc5 100644
--- a/doc/api/users.md
+++ b/doc/api/users.md
@@ -2,6 +2,8 @@
 
 ## List users
 
+Active users = Total accounts - Blocked users
+
 Get a list of users.
 
 This function takes pagination parameters `page` and `per_page` to restrict the list of users.
@@ -68,11 +70,11 @@ Username search is case insensitive.
 GET /users
 ```
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `order_by` | string | no | Return users ordered by `id`, `name`, `username`, `created_at`, or `updated_at` fields. Default is `id` |
-| `sort` | string | no | Return users sorted in `asc` or `desc` order. Default is `desc` |
-| `two_factor` | string | no | Filter users by Two-factor authentication. Filter values are `enabled` or `disabled`. By default it returns all users |
+| Attribute    | Type   | Required | Description |
+| ------------ | ------ | -------- | ----------- |
+| `order_by`   | string | no       | Return users ordered by `id`, `name`, `username`, `created_at`, or `updated_at` fields. Default is `id` |
+| `sort`       | string | no       | Return users sorted in `asc` or `desc` order. Default is `desc` |
+| `two_factor` | string | no       | Filter users by Two-factor authentication. Filter values are `enabled` or `disabled`. By default it returns all users |
 
 ```json
 [
@@ -145,6 +147,40 @@ GET /users
 ]
 ```
 
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see the `shared_runners_minutes_limit`, `extra_shared_runners_minutes_limit`, and `note` parameters.
+
+```json
+[
+  {
+    "id": 1,
+    ...
+    "shared_runners_minutes_limit": 133,
+    "extra_shared_runners_minutes_limit": 133,
+    "note": "DMCA Request: 2018-11-05 | DMCA Violation | Abuse | https://gitlab.zendesk.com/agent/tickets/123"
+    ...
+  }
+]
+```
+
+Users on GitLab [Silver or higher](https://about.gitlab.com/pricing/) will also see
+the `group_saml` provider option:
+
+```json
+[
+  {
+    "id": 1,
+    ...
+    "identities": [
+      {"provider": "github", "extern_uid": "2435223452345"},
+      {"provider": "bitbucket", "extern_uid": "john.smith"},
+      {"provider": "google_oauth2", "extern_uid": "8776128412476123468721346"},
+      {"provider": "group_saml", "extern_uid": "123789", "saml_provider_id": 10}
+    ],
+    ...
+  }
+]
+```
+
 You can lookup users by external UID and provider:
 
 ```
@@ -221,6 +257,8 @@ Parameters:
 
 - `id` (required) - The ID of a user
 
+Example Responses:
+
 ```json
 {
   "id": 1,
@@ -256,8 +294,41 @@ Parameters:
   "can_create_project": true,
   "two_factor_enabled": true,
   "external": false,
-  "private_profile": false,
-  "highest_role":10
+  "private_profile": false
+}
+```
+
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `shared_runners_minutes_limit`, `extra_shared_runners_minutes_limit`, and `note` parameters.
+
+```json
+{
+  "id": 1,
+  "username": "john_smith",
+  "shared_runners_minutes_limit": 133,
+  "extra_shared_runners_minutes_limit": 133,
+  "note": "DMCA Request: 2018-11-05 | DMCA Violation | Abuse | https://gitlab.zendesk.com/agent/tickets/123"
+  ...
+}
+```
+
+Users on GitLab.com [Silver, or higher](https://about.gitlab.com/pricing/) will also
+see the `group_saml` option:
+
+```json
+{
+  "id": 1,
+  "username": "john_smith",
+  "shared_runners_minutes_limit": 133,
+  "extra_shared_runners_minutes_limit": 133,
+  "note": "DMCA Request: 2018-11-05 | DMCA Violation | Abuse | https://gitlab.zendesk.com/agent/tickets/123"
+  "identities": [
+    {"provider": "github", "extern_uid": "2435223452345"},
+    {"provider": "bitbucket", "extern_uid": "john.smith"},
+    {"provider": "google_oauth2", "extern_uid": "8776128412476123468721346"},
+    {"provider": "group_saml", "extern_uid": "123789", "saml_provider_id": 10}
+  ],
+  ...
 }
 ```
 
@@ -269,7 +340,17 @@ GET /users/:id?with_custom_attributes=true
 
 ## User creation
 
-Creates a new user. Note only administrators can create new users. Either `password` or `reset_password` should be specified (`reset_password` takes priority). If `reset_password` is `false`, then `password` is required.
+Creates a new user. Note only administrators can create new
+users. Either `password`, `reset_password`, or `force_random_password`
+must be specified. If `reset_password` and `force_random_password` are
+both `false`, then `password` is required.
+
+Note that `force_random_password` and `reset_password` take priority
+over `password`. In addition, `reset_password` and
+`force_random_password` can be used together.
+
+NOTE: **Note:**
+From [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/29888/), `private_profile` will default to `false`.
 
 ```
 POST /users
@@ -296,9 +377,11 @@ Parameters:
 - `admin` (optional)             - User is admin - true or false (default)
 - `can_create_group` (optional)  - User can create groups - true or false
 - `skip_confirmation` (optional) - Skip confirmation - true or false (default)
-- `external` (optional)          - Flags the user as external - true or false(default)
+- `external` (optional)          - Flags the user as external - true or false (default)
 - `avatar` (optional)            - Image file for user's avatar
-- `private_profile` (optional)   - User's profile is private - true or false
+- `private_profile` (optional)   - User's profile is private - true or false (default)
+- `shared_runners_minutes_limit` (optional)       - Pipeline minutes quota for this user **(STARTER)**
+- `extra_shared_runners_minutes_limit` (optional) - Extra pipeline minutes quota for this user **(STARTER)**
 
 ## User modification
 
@@ -322,15 +405,21 @@ Parameters:
 - `projects_limit`                 - Limit projects each user can create
 - `extern_uid`                     - External UID
 - `provider`                       - External provider name
+- `group_id_for_saml` (optional)   - ID of group where SAML has been configured
 - `bio`                            - User's biography
 - `location` (optional)            - User's location
 - `public_email` (optional)        - The public email of the user
 - `admin` (optional)               - User is admin - true or false (default)
 - `can_create_group` (optional)    - User can create groups - true or false
 - `skip_reconfirmation` (optional) - Skip reconfirmation - true or false (default)
-- `external` (optional)            - Flags the user as external - true or false(default)
+- `external` (optional)            - Flags the user as external - true or false (default)
+- `shared_runners_minutes_limit` (optional) - Pipeline minutes quota for this user
+- `extra_shared_runners_minutes_limit` (optional) - Extra pipeline minutes quota for this user
 - `avatar` (optional)              - Image file for user's avatar
-- `private_profile` (optional)     - User's profile is private - true or false
+- `private_profile` (optional)     - User's profile is private - true or false (default)
+- `shared_runners_minutes_limit` (optional)       - Pipeline minutes quota for this user **(STARTER)**
+- `extra_shared_runners_minutes_limit` (optional) - Extra pipeline minutes quota for this user **(STARTER)**
+- `note` (optional) - Admin notes for this user **(STARTER)**
 
 On password update, user will be forced to change it upon next login.
 Note, at the moment this method does only return a `404` error,
@@ -353,9 +442,7 @@ Parameters:
   [moved to the ghost user](../user/profile/account/delete_account.md#associated-records)
   will be deleted instead, as well as groups owned solely by this user.
 
-## User
-
-### For normal users
+## List current user (for normal users)
 
 Gets currently authenticated user.
 
@@ -401,7 +488,7 @@ GET /user
 }
 ```
 
-### For admins
+## List current user (for admins)
 
 Parameters:
 
@@ -480,9 +567,9 @@ Get the status of a user.
 GET /users/:id_or_username/status
 ```
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id_or_username` | string | yes    | The id or username of the user to get a status of |
+| Attribute        | Type   | Required | Description |
+| ---------------- | ------ | -------- | ----------- |
+| `id_or_username` | string | yes      | The id or username of the user to get a status of |
 
 ```bash
 curl "https://gitlab.example.com/users/janedoe/status"
@@ -506,8 +593,8 @@ Set the status of the current user.
 PUT /user/status
 ```
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
+| Attribute | Type   | Required | Description |
+| --------- | ------ | -------- | ----------- |
 | `emoji`   | string | no     | The name of the emoji to use as status, if omitted `speech_balloon` is used. Emoji name can be one of the specified names in the [Gemojione index][gemojione-index]. |
 | `message` | string | no     | The message to set as a status. It can also contain emoji codes. |
 
@@ -527,9 +614,33 @@ Example responses
 }
 ```
 
+## User counts
+
+Get the counts (same as in top right menu) of the currently signed in user.
+
+| Attribute | Type | Description |
+| --------- | ---- | ----------- |
+| `merge_requests`   | number | Merge requests that are active and assigned to current user. |
+
+```
+GET /user_counts
+```
+
+```bash
+curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/user_counts"
+```
+
+Example response:
+
+```json
+{
+  "merge_requests": 4
+}
+```
+
 ## List user projects
 
-Please refer to the [List of user projects ](projects.md#list-user-projects).
+Please refer to the [List of user projects](projects.md#list-user-projects).
 
 ## List SSH keys
 
@@ -705,9 +816,9 @@ GET /user/gpg_keys/:key_id
 
 Parameters:
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `key_id`  | integer | yes   | The ID of the GPG key |
+| Attribute | Type    | Required | Description |
+| --------- | ------- | -------- | ----------- |
+| `key_id`  | integer | yes      | The ID of the GPG key |
 
 ```bash
 curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/user/gpg_keys/1
@@ -733,9 +844,9 @@ POST /user/gpg_keys
 
 Parameters:
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| key       | string | yes    | The new GPG key |
+| Attribute | Type   | Required | Description |
+| --------- | ------ | -------- | ----------- |
+| key       | string | yes      | The new GPG key |
 
 ```bash
 curl --data "key=-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\r\nxsBNBFV..."  --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/user/gpg_keys
@@ -763,9 +874,9 @@ DELETE /user/gpg_keys/:key_id
 
 Parameters:
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `key_id`  | integer | yes   | The ID of the GPG key |
+| Attribute | Type    | Required | Description |
+| --------- | ------- | -------- | ----------- |
+| `key_id`  | integer | yes      | The ID of the GPG key |
 
 ```bash
 curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/user/gpg_keys/1
@@ -783,9 +894,9 @@ GET /users/:id/gpg_keys
 
 Parameters:
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id`      | integer | yes   | The ID of the user |
+| Attribute | Type    | Required | Description |
+| --------- | ------- | -------- | ----------- |
+| `id`      | integer | yes      | The ID of the user |
 
 ```bash
 curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/users/2/gpg_keys
@@ -813,10 +924,10 @@ GET /users/:id/gpg_keys/:key_id
 
 Parameters:
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id`      | integer | yes   | The ID of the user |
-| `key_id`  | integer | yes   | The ID of the GPG key |
+| Attribute | Type    | Required | Description |
+| --------- | ------- | -------- | ----------- |
+| `id`      | integer | yes      | The ID of the user |
+| `key_id`  | integer | yes      | The ID of the GPG key |
 
 ```bash
 curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/users/2/gpg_keys/1
@@ -842,10 +953,10 @@ POST /users/:id/gpg_keys
 
 Parameters:
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id`      | integer | yes   | The ID of the user |
-| `key_id`  | integer | yes   | The ID of the GPG key |
+| Attribute | Type    | Required | Description |
+| --------- | ------- | -------- | ----------- |
+| `id`      | integer | yes      | The ID of the user |
+| `key_id`  | integer | yes      | The ID of the GPG key |
 
 ```bash
 curl --data "key=-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\r\nxsBNBFV..."  --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/users/2/gpg_keys
@@ -873,10 +984,10 @@ DELETE /users/:id/gpg_keys/:key_id
 
 Parameters:
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id`      | integer | yes   | The ID of the user |
-| `key_id`  | integer | yes   | The ID of the GPG key |
+| Attribute | Type    | Required | Description |
+| --------- | ------- | -------- | ----------- |
+| `id`      | integer | yes      | The ID of the user |
+| `key_id`  | integer | yes      | The ID of the GPG key |
 
 ```bash
 curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/users/2/gpg_keys/1
@@ -1057,10 +1168,10 @@ GET /users/:user_id/impersonation_tokens
 
 Parameters:
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `user_id` | integer | yes | The ID of the user |
-| `state`   | string  | no | filter tokens based on state (`all`, `active`, `inactive`) |
+| Attribute | Type    | Required | Description                                                |
+| --------- | ------- | -------- | ---------------------------------------------------------- |
+| `user_id` | integer | yes      | The ID of the user                                         |
+| `state`   | string  | no       | filter tokens based on state (`all`, `active`, `inactive`) |
 
 ```
 curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/users/42/impersonation_tokens
@@ -1109,10 +1220,10 @@ GET /users/:user_id/impersonation_tokens/:impersonation_token_id
 
 Parameters:
 
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `user_id` | integer | yes | The ID of the user |
-| `impersonation_token_id` | integer | yes | The ID of the impersonation token |
+| Attribute                | Type    | Required | Description                       |
+| ------------------------ | ------- | -------- | --------------------------------- |
+| `user_id`                | integer | yes      | The ID of the user                |
+| `impersonation_token_id` | integer | yes      | The ID of the impersonation token |
 
 ```
 curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/users/42/impersonation_tokens/2
@@ -1138,7 +1249,6 @@ Example response:
 ## Create an impersonation token
 
 > Requires admin permissions.
-
 > Token values are returned once. Make sure you save it - you won't be able to access it again.
 
 It creates a new impersonation token. Note that only administrators can do this.
@@ -1150,14 +1260,12 @@ settings page.
 POST /users/:user_id/impersonation_tokens
 ```
 
-Parameters:
-
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `user_id` | integer | yes | The ID of the user |
-| `name`    | string  | yes | The name of the impersonation token |
-| `expires_at` | date | no  | The expiration date of the impersonation token in ISO format (`YYYY-MM-DD`)|
-| `scopes` | array    | yes | The array of scopes of the impersonation token (`api`, `read_user`) |
+| Attribute    | Type    | Required | Description |
+| ------------ | ------- | -------- | ----------- |
+| `user_id`    | integer | yes      | The ID of the user |
+| `name`       | string  | yes      | The name of the impersonation token |
+| `expires_at` | date    | no       | The expiration date of the impersonation token in ISO format (`YYYY-MM-DD`)|
+| `scopes`     | array   | yes      | The array of scopes of the impersonation token (`api`, `read_user`) |
 
 ```
 curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "name=mytoken" --data "expires_at=2017-04-04" --data "scopes[]=api" https://gitlab.example.com/api/v4/users/42/impersonation_tokens
@@ -1204,15 +1312,15 @@ Parameters:
 
 ### Get user activities (admin only)
 
->**Note:** This API endpoint is only available on 8.15 (EE) and 9.1 (CE) and above.
+NOTE: **Note:** This API endpoint is only available on 8.15 (EE) and 9.1 (CE) and above.
 
 Get the last activity date for all users, sorted from oldest to newest.
 
 The activities that update the timestamp are:
 
-  - Git HTTP/SSH activities (such as clone, push)
-  - User logging in into GitLab
-  - User visiting pages related to Dashboards, Projects, Issues and Merge Requests ([introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/54947) in GitLab 11.8)
+- Git HTTP/SSH activities (such as clone, push)
+- User logging in into GitLab
+- User visiting pages related to Dashboards, Projects, Issues and Merge Requests ([introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/54947) in GitLab 11.8)
 
 By default, it shows the activity for all users in the last 6 months, but this can be
 amended by using the `from` parameter.