diff options
Diffstat (limited to 'doc/api/users.md')
| -rw-r--r-- | doc/api/users.md | 116 |
1 files changed, 98 insertions, 18 deletions
diff --git a/doc/api/users.md b/doc/api/users.md index 4ecb3d48c0f..a2293090209 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -6,6 +6,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Users API **(FREE)** +This documentation has information on API calls, parameters and responses for the Users API. + +For information on user activities that update the user event timestamps, see [get user activities](#get-user-activities). + ## List users Get a list of users. @@ -41,7 +45,7 @@ GET /users You can also use `?search=` to search for users by name, username, or public email. For example, `/users?search=John`. When you search for a: -- Public email, you must use the full email address to get an exact match. +- Public email, you must use the full email address to get an exact match. A search might return a partial match. For example, if you search for the email `on@example.com`, the search can return both `on@example.com` and `jon@example.com`. - Name or username, you do not have to get an exact match because this is a fuzzy search. In addition, you can lookup users by username: @@ -209,7 +213,7 @@ GET /users ] ``` -Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see the `shared_runners_minutes_limit`, `extra_shared_runners_minutes_limit`, `is_auditor`, and `using_license_seat` parameters. +Users on [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/) also see the `shared_runners_minutes_limit`, `extra_shared_runners_minutes_limit`, `is_auditor`, and `using_license_seat` parameters. ```json [ @@ -225,7 +229,7 @@ Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see ] ``` -Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see +Users on [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/) also see the `group_saml` provider option and `provisioned_by_group_id` parameter: ```json @@ -409,7 +413,7 @@ Example Responses: NOTE: The `plan` and `trial` parameters are only available on GitLab Enterprise Edition. -Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see +Users on [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/) also see the `shared_runners_minutes_limit`, `is_auditor`, and `extra_shared_runners_minutes_limit` parameters. ```json @@ -423,7 +427,7 @@ the `shared_runners_minutes_limit`, `is_auditor`, and `extra_shared_runners_minu } ``` -Users on [GitLab.com Premium or higher](https://about.gitlab.com/pricing/) also +Users on [GitLab.com Premium or Ultimate](https://about.gitlab.com/pricing/) also see the `group_saml` option and `provisioned_by_group_id` parameter: ```json @@ -663,7 +667,7 @@ GET /user } ``` -Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see the `shared_runners_minutes_limit`, `extra_shared_runners_minutes_limit` parameters. +Users on [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/) also see the `shared_runners_minutes_limit`, `extra_shared_runners_minutes_limit` parameters. ### For administrators **(FREE SELF)** @@ -727,7 +731,7 @@ Parameters: } ``` -Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see these +Users on [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/) also see these parameters: - `shared_runners_minutes_limit` @@ -838,7 +842,8 @@ Example response: "id": 1, "user_id": 1 "view_diffs_file_by_file": true, - "show_whitespace_in_diffs": false + "show_whitespace_in_diffs": false, + "pass_user_identities_to_ci_jwt": false } ``` @@ -859,16 +864,18 @@ PUT /user/preferences "id": 1, "user_id": 1 "view_diffs_file_by_file": true, - "show_whitespace_in_diffs": false + "show_whitespace_in_diffs": false, + "pass_user_identities_to_ci_jwt": false } ``` Parameters: -| Attribute | Required | Description | -| :--------------------------- | :------- | :---------------------------------------------------------- | -| `view_diffs_file_by_file` | Yes | Flag indicating the user sees only one file diff per page. | -| `show_whitespace_in_diffs` | Yes | Flag indicating the user sees whitespace changes in diffs. | +| Attribute | Required | Description | +| :------------------------------- | :------- | :--------------------------------------------------------------------------- | +| `view_diffs_file_by_file` | Yes | Flag indicating the user sees only one file diff per page. | +| `show_whitespace_in_diffs` | Yes | Flag indicating the user sees whitespace changes in diffs. | +| `pass_user_identities_to_ci_jwt` | Yes | Flag indicating the user passes their external identities as CI information. This attribute does not contain enough information to identify or authorize the user in an external system. The attribute is internal to GitLab, and must not be passed to third-party services. | ## User follow @@ -1301,7 +1308,25 @@ Parameters: | `key` | string | yes | New GPG key | ```shell -curl --data "key=-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\r\nxsBNBFV..." \ + +export KEY="$( gpg --armor --export <your_gpg_key_id>)" + +curl --data-urlencode "key=-----BEGIN PGP PUBLIC KEY BLOCK----- +> xsBNBFVjnlIBCACibzXOLCiZiL2oyzYUaTOCkYnSUhymg3pdbfKtd4mpBa58xKBj +> t1pTHVpw3Sk03wmzhM/Ndlt1AV2YhLv++83WKr+gAHFYFiCV/tnY8bx3HqvVoy8O +> CfxWhw4QZK7+oYzVmJj8ZJm3ZjOC4pzuegNWlNLCUdZDx9OKlHVXLCX1iUbjdYWa +> qKV6tdV8hZolkbyjedQgrpvoWyeSHHpwHF7yk4gNJWMMI5rpcssL7i6mMXb/sDzO +> VaAtU5wiVducsOa01InRFf7QSTxoAm6Xy0PGv/k48M6xCALa9nY+BzlOv47jUT57 +> vilf4Szy9dKD0v9S0mQ+IHB+gNukWrnwtXx5ABEBAAHNFm5hbWUgKGNvbW1lbnQp +> IDxlbUBpbD7CwHUEEwECACkFAlVjnlIJEINgJNgv009/AhsDAhkBBgsJCAcDAgYV +> CAIJCgsEFgIDAQAAxqMIAFBHuBA8P1v8DtHonIK8Lx2qU23t8Mh68HBIkSjk2H7/ +> oO2cDWCw50jZ9D91PXOOyMPvBWV2IE3tARzCvnNGtzEFRtpIEtZ0cuctxeIF1id5 +> crfzdMDsmZyRHAOoZ9VtuD6mzj0ybQWMACb7eIHjZDCee3Slh3TVrLy06YRdq2I4 +> bjMOPePtK5xnIpHGpAXkB3IONxyITpSLKsA4hCeP7gVvm7r7TuQg1ygiUBlWbBYn +> iE5ROzqZjG1s7dQNZK/riiU2umGqGuwAb2IPvNiyuGR3cIgRE4llXH/rLuUlspAp +> o4nlxaz65VucmNbN1aMbDXLJVSqR1DuE00vEsL1AItI= +> =XQoy +> -----END PGP PUBLIC KEY BLOCK-----" \ --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/user/gpg_keys" ``` @@ -1311,7 +1336,7 @@ Example response: [ { "id": 1, - "key": "-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\r\nxsBNBFVjnlIBCACibzXOLCiZiL2oyzYUaTOCkYnSUhymg3pdbfKtd4mpBa58xKBj\r\nt1pTHVpw3Sk03wmzhM/Ndlt1AV2YhLv++83WKr+gAHFYFiCV/tnY8bx3HqvVoy8O\r\nCfxWhw4QZK7+oYzVmJj8ZJm3ZjOC4pzuegNWlNLCUdZDx9OKlHVXLCX1iUbjdYWa\r\nqKV6tdV8hZolkbyjedQgrpvoWyeSHHpwHF7yk4gNJWMMI5rpcssL7i6mMXb/sDzO\r\nVaAtU5wiVducsOa01InRFf7QSTxoAm6Xy0PGv/k48M6xCALa9nY+BzlOv47jUT57\r\nvilf4Szy9dKD0v9S0mQ+IHB+gNukWrnwtXx5ABEBAAHNFm5hbWUgKGNvbW1lbnQp\r\nIDxlbUBpbD7CwHUEEwECACkFAlVjnlIJEINgJNgv009/AhsDAhkBBgsJCAcDAgYV\r\nCAIJCgsEFgIDAQAAxqMIAFBHuBA8P1v8DtHonIK8Lx2qU23t8Mh68HBIkSjk2H7/\r\noO2cDWCw50jZ9D91PXOOyMPvBWV2IE3tARzCvnNGtzEFRtpIEtZ0cuctxeIF1id5\r\ncrfzdMDsmZyRHAOoZ9VtuD6mzj0ybQWMACb7eIHjZDCee3Slh3TVrLy06YRdq2I4\r\nbjMOPePtK5xnIpHGpAXkB3IONxyITpSLKsA4hCeP7gVvm7r7TuQg1ygiUBlWbBYn\r\niE5ROzqZjG1s7dQNZK/riiU2umGqGuwAb2IPvNiyuGR3cIgRE4llXH/rLuUlspAp\r\no4nlxaz65VucmNbN1aMbDXLJVSqR1DuE00vEsL1AItI=\r\n=XQoy\r\n-----END PGP PUBLIC KEY BLOCK-----", + "key": "-----BEGIN PGP PUBLIC KEY BLOCK-----\nxsBNBFVjnlIBCACibzXOLCiZiL2oyzYUaTOCkYnSUhymg3pdbfKtd4mpBa58xKBj\nt1pTHVpw3Sk03wmzhM/Ndlt1AV2YhLv++83WKr+gAHFYFiCV/tnY8bx3HqvVoy8O\nCfxWhw4QZK7+oYzVmJj8ZJm3ZjOC4pzuegNWlNLCUdZDx9OKlHVXLCX1iUbjdYWa\nqKV6tdV8hZolkbyjedQgrpvoWyeSHHpwHF7yk4gNJWMMI5rpcssL7i6mMXb/sDzO\nVaAtU5wiVducsOa01InRFf7QSTxoAm6Xy0PGv/k48M6xCALa9nY+BzlOv47jUT57\nvilf4Szy9dKD0v9S0mQ+IHB+gNukWrnwtXx5ABEBAAHNFm5hbWUgKGNvbW1lbnQp\nIDxlbUBpbD7CwHUEEwECACkFAlVjnlIJEINgJNgv009/AhsDAhkBBgsJCAcDAgYV\nCAIJCgsEFgIDAQAAxqMIAFBHuBA8P1v8DtHonIK8Lx2qU23t8Mh68HBIkSjk2H7/\noO2cDWCw50jZ9D91PXOOyMPvBWV2IE3tARzCvnNGtzEFRtpIEtZ0cuctxeIF1id5\ncrfzdMDsmZyRHAOoZ9VtuD6mzj0ybQWMACb7eIHjZDCee3Slh3TVrLy06YRdq2I4\nbjMOPePtK5xnIpHGpAXkB3IONxyITpSLKsA4hCeP7gVvm7r7TuQg1ygiUBlWbBYn\niE5ROzqZjG1s7dQNZK/riiU2umGqGuwAb2IPvNiyuGR3cIgRE4llXH/rLuUlspAp\no4nlxaz65VucmNbN1aMbDXLJVSqR1DuE00vEsL1AItI=\n=XQoy\n-----END PGP PUBLIC KEY BLOCK-----", "created_at": "2017-09-05T09:17:46.264Z" } ] @@ -1413,7 +1438,22 @@ Parameters: | `key_id` | integer | yes | ID of the GPG key | ```shell -curl --data "key=-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\r\nxsBNBFV..." \ +curl --data-urlencode "key=-----BEGIN PGP PUBLIC KEY BLOCK----- +> xsBNBFVjnlIBCACibzXOLCiZiL2oyzYUaTOCkYnSUhymg3pdbfKtd4mpBa58xKBj +> t1pTHVpw3Sk03wmzhM/Ndlt1AV2YhLv++83WKr+gAHFYFiCV/tnY8bx3HqvVoy8O +> CfxWhw4QZK7+oYzVmJj8ZJm3ZjOC4pzuegNWlNLCUdZDx9OKlHVXLCX1iUbjdYWa +> qKV6tdV8hZolkbyjedQgrpvoWyeSHHpwHF7yk4gNJWMMI5rpcssL7i6mMXb/sDzO +> VaAtU5wiVducsOa01InRFf7QSTxoAm6Xy0PGv/k48M6xCALa9nY+BzlOv47jUT57 +> vilf4Szy9dKD0v9S0mQ+IHB+gNukWrnwtXx5ABEBAAHNFm5hbWUgKGNvbW1lbnQp +> IDxlbUBpbD7CwHUEEwECACkFAlVjnlIJEINgJNgv009/AhsDAhkBBgsJCAcDAgYV +> CAIJCgsEFgIDAQAAxqMIAFBHuBA8P1v8DtHonIK8Lx2qU23t8Mh68HBIkSjk2H7/ +> oO2cDWCw50jZ9D91PXOOyMPvBWV2IE3tARzCvnNGtzEFRtpIEtZ0cuctxeIF1id5 +> crfzdMDsmZyRHAOoZ9VtuD6mzj0ybQWMACb7eIHjZDCee3Slh3TVrLy06YRdq2I4 +> bjMOPePtK5xnIpHGpAXkB3IONxyITpSLKsA4hCeP7gVvm7r7TuQg1ygiUBlWbBYn +> iE5ROzqZjG1s7dQNZK/riiU2umGqGuwAb2IPvNiyuGR3cIgRE4llXH/rLuUlspAp +> o4nlxaz65VucmNbN1aMbDXLJVSqR1DuE00vEsL1AItI= +> =XQoy +> -----END PGP PUBLIC KEY BLOCK-----" \ --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/2/gpg_keys" ``` @@ -1423,7 +1463,7 @@ Example response: [ { "id": 1, - "key": "-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\r\nxsBNBFVjnlIBCACibzXOLCiZiL2oyzYUaTOCkYnSUhymg3pdbfKtd4mpBa58xKBj\r\nt1pTHVpw3Sk03wmzhM/Ndlt1AV2YhLv++83WKr+gAHFYFiCV/tnY8bx3HqvVoy8O\r\nCfxWhw4QZK7+oYzVmJj8ZJm3ZjOC4pzuegNWlNLCUdZDx9OKlHVXLCX1iUbjdYWa\r\nqKV6tdV8hZolkbyjedQgrpvoWyeSHHpwHF7yk4gNJWMMI5rpcssL7i6mMXb/sDzO\r\nVaAtU5wiVducsOa01InRFf7QSTxoAm6Xy0PGv/k48M6xCALa9nY+BzlOv47jUT57\r\nvilf4Szy9dKD0v9S0mQ+IHB+gNukWrnwtXx5ABEBAAHNFm5hbWUgKGNvbW1lbnQp\r\nIDxlbUBpbD7CwHUEEwECACkFAlVjnlIJEINgJNgv009/AhsDAhkBBgsJCAcDAgYV\r\nCAIJCgsEFgIDAQAAxqMIAFBHuBA8P1v8DtHonIK8Lx2qU23t8Mh68HBIkSjk2H7/\r\noO2cDWCw50jZ9D91PXOOyMPvBWV2IE3tARzCvnNGtzEFRtpIEtZ0cuctxeIF1id5\r\ncrfzdMDsmZyRHAOoZ9VtuD6mzj0ybQWMACb7eIHjZDCee3Slh3TVrLy06YRdq2I4\r\nbjMOPePtK5xnIpHGpAXkB3IONxyITpSLKsA4hCeP7gVvm7r7TuQg1ygiUBlWbBYn\r\niE5ROzqZjG1s7dQNZK/riiU2umGqGuwAb2IPvNiyuGR3cIgRE4llXH/rLuUlspAp\r\no4nlxaz65VucmNbN1aMbDXLJVSqR1DuE00vEsL1AItI=\r\n=XQoy\r\n-----END PGP PUBLIC KEY BLOCK-----", + "key": "-----BEGIN PGP PUBLIC KEY BLOCK-----\nxsBNBFVjnlIBCACibzXOLCiZiL2oyzYUaTOCkYnSUhymg3pdbfKtd4mpBa58xKBj\nt1pTHVpw3Sk03wmzhM/Ndlt1AV2YhLv++83WKr+gAHFYFiCV/tnY8bx3HqvVoy8O\nCfxWhw4QZK7+oYzVmJj8ZJm3ZjOC4pzuegNWlNLCUdZDx9OKlHVXLCX1iUbjdYWa\nqKV6tdV8hZolkbyjedQgrpvoWyeSHHpwHF7yk4gNJWMMI5rpcssL7i6mMXb/sDzO\nVaAtU5wiVducsOa01InRFf7QSTxoAm6Xy0PGv/k48M6xCALa9nY+BzlOv47jUT57\nvilf4Szy9dKD0v9S0mQ+IHB+gNukWrnwtXx5ABEBAAHNFm5hbWUgKGNvbW1lbnQp\nIDxlbUBpbD7CwHUEEwECACkFAlVjnlIJEINgJNgv009/AhsDAhkBBgsJCAcDAgYV\nCAIJCgsEFgIDAQAAxqMIAFBHuBA8P1v8DtHonIK8Lx2qU23t8Mh68HBIkSjk2H7/\noO2cDWCw50jZ9D91PXOOyMPvBWV2IE3tARzCvnNGtzEFRtpIEtZ0cuctxeIF1id5\ncrfzdMDsmZyRHAOoZ9VtuD6mzj0ybQWMACb7eIHjZDCee3Slh3TVrLy06YRdq2I4\nbjMOPePtK5xnIpHGpAXkB3IONxyITpSLKsA4hCeP7gVvm7r7TuQg1ygiUBlWbBYn\niE5ROzqZjG1s7dQNZK/riiU2umGqGuwAb2IPvNiyuGR3cIgRE4llXH/rLuUlspAp\no4nlxaz65VucmNbN1aMbDXLJVSqR1DuE00vEsL1AItI=\n=XQoy\n-----END PGP PUBLIC KEY BLOCK-----", "created_at": "2017-09-05T09:17:46.264Z" } ] @@ -2027,7 +2067,7 @@ Pre-requisite: Get the last activity date for all users, sorted from oldest to newest. -The activities that update the timestamp are: +The activities that update the user event timestamps (`last_activity_on` and `current_sign_in_at`) are: - Git HTTP/SSH activities (such as clone, push) - User logging in to GitLab @@ -2163,3 +2203,43 @@ Returns: - `400 Bad request` if two factor authentication is not enabled for the specified user. - `403 Forbidden` if not authenticated as an administrator. - `404 User Not Found` if user cannot be found. + +## Create a CI runner **(FREE SELF)** + +It creates a new runner, linked to the current user. + +Requires administrator access or ownership of the target namespace or project. Token values are returned once. Make sure you save it because you can't access +it again. + +```plaintext +POST /user/runners +``` + +| Attribute | Type | Required | Description | +|--------------------|--------------|----------|---------------------------------------------------------------------------------------------------| +| `runner_type` | string | yes | Specifies the scope of the runner; `instance_type`, `group_type`, or `project_type`. | +| `group_id` | integer | no | The ID of the group that the runner is created in. Required if `runner_type` is `group_type`. | +| `project_id` | integer | no | The ID of the project that the runner is created in. Required if `runner_type` is `project_type`. | +| `description` | string | no | Description of the runner. | +| `paused` | boolean | no | Specifies if the runner should ignore new jobs. | +| `locked` | boolean | no | Specifies if the runner should be locked for the current project. | +| `run_untagged` | boolean | no | Specifies if the runner should handle untagged jobs. | +| `tag_list` | string array | no | A list of runner tags. | +| `access_level` | string | no | The access level of the runner; `not_protected` or `ref_protected`. | +| `maximum_timeout` | integer | no | Maximum timeout that limits the amount of time (in seconds) that runners can run jobs. | +| `maintenance_note` | string | no | Free-form maintenance notes for the runner (1024 characters). | + +```shell +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "runner_type=instance_type" \ + "https://gitlab.example.com/api/v4/user/runners" +``` + +Example response: + +```json +{ + "id": 9171, + "token": "glrt-kyahzxLaj4Dc1jQf4xjX", + "token_expires_at": null +} +``` |