{{< details >}}

  • Tier: Free, Premium, Ultimate
  • Offering: JihuLab.com, 极狐GitLab 私有化部署, 极狐GitLab Dedicated

{{< /details >}}

你可以通过使用 REST API 来管理你的账户和管理其他用户。

列出用户

获取用户列表。

使用分页参数 page 和 per_page 来限制用户列表。

作为普通用户

{{< history >}}

  • 在极狐GitLab 16.5 中引入了 Keyset 分页。

{{< /history >}}

GET /users

支持的属性：

属性 类型 必需 描述
username string 否 获取特定用户名的单个用户。
search string 否 通过名称、用户名或公开邮箱搜索用户。
active boolean 否 仅过滤活跃用户。默认值为 false。
external boolean 否 仅过滤外部用户。默认值为 false。
blocked boolean 否 仅过滤被封锁的用户。默认值为 false。
humans boolean 否 仅过滤不是机器人或内部用户的普通用户。默认值为 false。
created_after DateTime 否 返回指定时间后创建的用户。
created_before DateTime 否 返回指定时间前创建的用户。
exclude_active boolean 否 仅过滤非活跃用户。默认值为 false。
exclude_external boolean 否 仅过滤非外部用户。默认值为 false。
exclude_humans boolean 否 仅过滤机器人或内部用户。默认值为 false。
exclude_internal boolean 否 仅过滤非内部用户。默认值为 false。
without_project_bots boolean 否 过滤没有项目机器人的用户。默认值为 false。

示例响应：

[
  {
    "id": 1,
    "username": "john_smith",
    "name": "John Smith",
    "state": "active",
    "locked": false,
    "avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg",
    "web_url": "http://localhost:3000/john_smith"
  },
  {
    "id": 2,
    "username": "jack_smith",
    "name": "Jack Smith",
    "state": "blocked",
    "locked": false,
    "avatar_url": "http://gravatar.com/../e32131cd8.jpeg",
    "web_url": "http://localhost:3000/jack_smith"
  }
]

此端点支持keyset 分页。在极狐GitLab 17.0 及更高版本中，响应数量为 50,000 及以上时需要使用 keyset 分页。

你还可以使用 ?search= 来通过名称、用户名或公开邮箱搜索用户。例如，/users?search=John。当你搜索：

  • 公开邮箱时，必须使用完整的邮箱地址才能获得准确匹配。
  • 名称或用户名时，不必获得准确匹配，因为这是模糊搜索。

此外，你可以通过用户名查找用户：

GET /users?username=:username

例如：

GET /users?username=jack_smith

{{< alert type=”note” >}}

用户名搜索不区分大小写。

{{< /alert >}}

此外，你可以根据状态 blocked 和 active 过滤用户。它不支持 active=false 或 blocked=false。

GET /users?active=true

GET /users?blocked=true

此外，你可以仅使用 external=true 来搜索外部用户。它不支持 external=false。

GET /users?external=true

极狐GitLab 支持机器人用户，例如警报机器人或支持机器人。你可以使用 exclude_internal=true 参数从用户列表中排除以下类型的内部用户：

  • 警报机器人
  • 支持机器人

然而，此操作不会排除项目的机器人用户或群组的机器人用户。

GET /users?exclude_internal=true

此外，要从用户列表中排除外部用户，你可以使用参数 exclude_external=true。

GET /users?exclude_external=true

要排除项目的机器人用户和群组的机器人用户，你可以使用参数 without_project_bots=true。

GET /users?without_project_bots=true

作为管理员

{{< details >}}

  • Tier: Free, Premium, Ultimate
  • Offering: 极狐GitLab 私有化部署, 极狐GitLab Dedicated

{{< /details >}}

{{< history >}}

  • 在极狐GitLab 15.6 中响应中的 created_by 字段被引入。
  • 在极狐GitLab 16.1 中响应中的 scim_identities 字段被引入。
  • 在极狐GitLab 16.2 中响应中的 auditors 字段被引入。
  • 在极狐GitLab 16.7 中响应中的 email_reset_offered_at 字段被引入。

{{< /history >}}

GET /users

你可以使用所有为所有人提供的参数加上这些仅管理员可用的附加属性。

支持的属性：

属性 类型 必需 描述
search string 否 通过名称、用户名、公开邮箱或私人邮箱搜索用户。
extern_uid string 否 获取具有特定外部认证提供者 UID 的单个用户。
provider string 否 外部提供者。
order_by string 否 按 id、name、username、created_at 或 updated_at 字段排序返回用户。默认值为 id
sort string 否 返回按 asc 或 desc 排序的用户。默认值为 desc
two_factor string 否 按双因素认证过滤用户。过滤值为 enabled 或 disabled。默认情况下返回所有用户
without_projects boolean 否 过滤没有项目的用户。默认值为 false，这意味着返回所有用户，包括有项目和没有项目的用户。
admins boolean 否 仅返回管理员。默认值为 false
auditors boolean 否 仅返回审计员用户。默认值为 false。如果未包含，则返回所有用户。仅限专业版和旗舰版。
saml_provider_id number 否 仅返回由指定的 SAML 提供者 ID 创建的用户。如果未包含，则返回所有用户。仅限专业版和旗舰版。
skip_ldap boolean 否 跳过 LDAP 用户。仅限专业版和旗舰版。

示例响应：

[
  {
    "id": 1,
    "username": "john_smith",
    "email": "john@example.com",
    "name": "John Smith",
    "state": "active",
    "locked": false,
    "avatar_url": "http://localhost:3000/uploads/user/avatar/1/index.jpg",
    "web_url": "http://localhost:3000/john_smith",
    "created_at": "2012-05-23T08:00:58Z",
    "is_admin": false,
    "bio": "",
    "location": null,
    "skype": "",
    "linkedin": "",
    "twitter": "",
    "discord": "",
    "website_url": "",
    "organization": "",
    "job_title": "",
    "last_sign_in_at": "2012-06-01T11:41:01Z",
    "confirmed_at": "2012-05-23T09:05:22Z",
    "theme_id": 1,
    "last_activity_on": "2012-05-23",
    "color_scheme_id": 2,
    "projects_limit": 100,
    "current_sign_in_at": "2012-06-02T06:36:55Z",
    "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"}
    ],
    "can_create_group": true,
    "can_create_project": true,
    "two_factor_enabled": true,
    "external": false,
    "private_profile": false,
    "current_sign_in_ip": "196.165.1.102",
    "last_sign_in_ip": "172.127.2.22",
    "namespace_id": 1,
    "created_by": null,
    "email_reset_offered_at": null
  },
  {
    "id": 2,
    "username": "jack_smith",
    "email": "jack@example.com",
    "name": "Jack Smith",
    "state": "blocked",
    "locked": false,
    "avatar_url": "http://localhost:3000/uploads/user/avatar/2/index.jpg",
    "web_url": "http://localhost:3000/jack_smith",
    "created_at": "2012-05-23T08:01:01Z",
    "is_admin": false,
    "bio": "",
    "location": null,
    "skype": "",
    "linkedin": "",
    "twitter": "",
    "discord": "",
    "website_url": "",
    "organization": "",
    "job_title": "",
    "last_sign_in_at": null,
    "confirmed_at": "2012-05-30T16:53:06.148Z",
    "theme_id": 1,
    "last_activity_on": "2012-05-23",
    "color_scheme_id": 3,
    "projects_limit": 100,
    "current_sign_in_at": "2014-03-19T17:54:13Z",
    "identities": [],
    "can_create_group": true,
    "can_create_project": true,
    "two_factor_enabled": true,
    "external": false,
    "private_profile": false,
    "current_sign_in_ip": "10.165.1.102",
    "last_sign_in_ip": "172.127.2.22",
    "namespace_id": 2,
    "created_by": null,
    "email_reset_offered_at": null
  }
]

在极狐GitLab 专业版或旗舰版中的用户还可以看到 shared_runners_minutes_limit、extra_shared_runners_minutes_limit、is_auditor 和 using_license_seat 参数。

[
  {
    "id": 1,
    ...
    "shared_runners_minutes_limit": 133,
    "extra_shared_runners_minutes_limit": 133,
    "is_auditor": false,
    "using_license_seat": true
    ...
  }
]

在极狐GitLab 专业版或旗舰版中的用户还可以看到 group_saml 提供者选项和 provisioned_by_group_id 参数：

[
  {
    "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}
    ],
    "provisioned_by_group_id": 123789
    ...
  }
]

你还可以使用 ?search= 来通过名称、用户名或邮箱搜索用户。例如，/users?search=John。当你搜索：

  • 邮箱时，必须使用完整的邮箱地址才能获得准确匹配。作为管理员，你可以搜索公开和私人邮箱地址。
  • 名称或用户名时，不必获得准确匹配，因为这是模糊搜索。

你可以通过外部 UID 和提供者查找用户：

GET /users?extern_uid=:extern_uid&provider=:provider

例如：

GET /users?extern_uid=1234567&provider=github

在极狐GitLab 专业版或旗舰版中的用户可以使用 scim 提供者：

GET /users?extern_uid=1234567&provider=scim

你可以通过创建日期时间范围搜索用户：

GET /users?created_before=2001-01-02T00:00:00.060Z&created_after=1999-01-02T00:00:00.060

你可以通过以下方式搜索没有项目的用户：/users?without_projects=true

你可以通过自定义属性进行过滤：

GET /users?custom_attributes[key]=value&custom_attributes[other_key]=other_value

你可以在响应中包含用户的自定义属性：

GET /users?with_custom_attributes=true

你可以使用 created_by 参数查看用户账户是否由以下方式创建：

如果返回值为 null，则表示账户是由自行注册账户的用户创建的。

获取单个用户

获取单个用户。

作为普通用户

作为普通用户获取单个用户。

前提条件：

  • 你必须登录才能使用此端点。
GET /users/:id

支持的属性：

属性 类型 必需 描述
id integer 是 用户的 ID

示例响应：

{
  "id": 1,
  "username": "john_smith",
  "name": "John Smith",
  "state": "active",
  "locked": false,
  "avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg",
  "web_url": "http://localhost:3000/john_smith",
  "created_at": "2012-05-23T08:00:58Z",
  "bio": "",
  "bot": false,
  "location": null,
  "public_email": "john@example.com",
  "skype": "",
  "linkedin": "",
  "twitter": "",
  "discord": "",
  "website_url": "",
  "organization": "",
  "job_title": "Operations Specialist",
  "pronouns": "he/him",
  "work_information": null,
  "followers": 1,
  "following": 1,
  "local_time": "3:38 PM",
  "is_followed": false
}

作为管理员

{{< details >}}

  • Tier: Free, Premium, Ultimate
  • Offering: 极狐GitLab 私有化部署, 极狐GitLab Dedicated

{{< /details >}}

{{< history >}}

  • 在极狐GitLab 15.6 中响应中的 created_by 字段被引入。
  • 在极狐GitLab 16.7 中响应中的 email_reset_offered_at 字段被引入。

{{< /history >}}

作为管理员获取单个用户。

GET /users/:id

支持的属性：

属性 类型 必需 描述
id integer 是 用户的 ID

示例响应：

{
  "id": 1,
  "username": "john_smith",
  "email": "john@example.com",
  "name": "John Smith",
  "state": "active",
  "locked": false,
  "avatar_url": "http://localhost:3000/uploads/user/avatar/1/index.jpg",
  "web_url": "http://localhost:3000/john_smith",
  "created_at": "2012-05-23T08:00:58Z",
  "is_admin": false,
  "bio": "",
  "location": null,
  "public_email": "john@example.com",
  "skype": "",
  "linkedin": "",
  "twitter": "",
  "discord": "",
  "website_url": "",
  "organization": "",
  "job_title": "Operations Specialist",
  "pronouns": "he/him",
  "work_information": null,
  "followers": 1,
  "following": 1,
  "local_time": "3:38 PM",
  "last_sign_in_at": "2012-06-01T11:41:01Z",
  "confirmed_at": "2012-05-23T09:05:22Z",
  "theme_id": 1,
  "last_activity_on": "2012-05-23",
  "color_scheme_id": 2,
  "projects_limit": 100,
  "current_sign_in_at": "2012-06-02T06:36:55Z",
  "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"}
  ],
  "can_create_group": true,
  "can_create_project": true,
  "two_factor_enabled": true,
  "external": false,
  "private_profile": false,
  "commit_email": "john-codes@example.com",
  "current_sign_in_ip": "196.165.1.102",
  "last_sign_in_ip": "172.127.2.22",
  "plan": "gold",
  "trial": true,
  "sign_in_count": 1337,
  "namespace_id": 1,
  "created_by": null,
  "email_reset_offered_at": null
}

{{< alert type=”note” >}}

plan 和 trial 参数仅在极狐GitLab 企业版中可用。

{{< /alert >}}

在极狐GitLab 专业版或旗舰版中的用户还可以看到 shared_runners_minutes_limit、is_auditor 和 extra_shared_runners_minutes_limit 参数。

{
  "id": 1,
  "username": "john_smith",
  "is_auditor": false,
  "shared_runners_minutes_limit": 133,
  "extra_shared_runners_minutes_limit": 133,
  ...
}

在JihuLab.com 专业版或旗舰版中的用户还可以看到 group_saml 选项和 provisioned_by_group_id 参数：

{
  "id": 1,
  "username": "john_smith",
  "shared_runners_minutes_limit": 133,
  "extra_shared_runners_minutes_limit": 133,
  "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}
  ],
  "provisioned_by_group_id": 123789
  ...
}

在JihuLab.com 专业版或旗舰版中的用户还可以看到 scim_identities 参数：

{
  ...
  "extra_shared_runners_minutes_limit": null,
  "scim_identities": [
      {"extern_uid": "2435223452345", "group_id": "3", "active": true},
      {"extern_uid": "john.smith", "group_id": "42", "active": false}
    ]
  ...
}

管理员可以使用 created_by 参数查看用户账户是否由以下方式创建：

如果返回值为 null，则表示账户是由自行注册账户的用户创建的。

你可以在响应中包含用户的自定义属性：

GET /users/:id?with_custom_attributes=true

获取当前用户

获取当前用户。

作为普通用户

获取你的用户详细信息。

GET /user

示例响应：

{
  "id": 1,
  "username": "john_smith",
  "email": "john@example.com",
  "name": "John Smith",
  "state": "active",
  "locked": false,
  "avatar_url": "http://localhost:3000/uploads/user/avatar/1/index.jpg",
  "web_url": "http://localhost:3000/john_smith",
  "created_at": "2012-05-23T08:00:58Z",
  "bio": "",
  "location": null,
  "public_email": "john@example.com",
  "skype": "",
  "linkedin": "",
  "twitter": "",
  "discord": "",
  "website_url": "",
  "organization": "",
  "job_title": "",
  "pronouns": "he/him",
  "bot": false,
  "work_information": null,
  "followers": 0,
  "following": 0,
  "local_time": "3:38 PM",
  "last_sign_in_at": "2012-06-01T11:41:01Z",
  "confirmed_at": "2012-05-23T09:05:22Z",
  "theme_id": 1,
  "last_activity_on": "2012-05-23",
  "color_scheme_id": 2,
  "projects_limit": 100,
  "current_sign_in_at": "2012-06-02T06:36:55Z",
  "identities": [
    {"provider": "github", "extern_uid": "2435223452345"},
    {"provider": "bitbucket", "extern_uid": "john_smith"},
    {"provider": "google_oauth2", "extern_uid": "8776128412476123468721346"}
  ],
  "can_create_group": true,
  "can_create_project": true,
  "two_factor_enabled": true,
  "external": false,
  "private_profile": false,
  "commit_email": "admin@example.com",
}

在极狐GitLab 专业版或旗舰版中的用户还可以看到 shared_runners_minutes_limit、extra_shared_runners_minutes_limit 参数。

作为管理员

{{< details >}}

  • Tier: Free, Premium, Ultimate
  • Offering: 极狐GitLab 私有化部署, 极狐GitLab Dedicated

{{< /details >}}

{{< history >}}

  • 在极狐GitLab 15.6 中响应中的 created_by 字段被引入。
  • 在极狐GitLab 16.7 中响应中的 email_reset_offered_at 字段被引入。

{{< /history >}}

获取你的用户详细信息或其他用户的详细信息。

GET /user

支持的属性：

属性 类型 必需 描述
sudo integer 否 用户的 ID，用于替他们进行调用 
{
  "id": 1,
  "username": "john_smith",
  "email": "john@example.com",
  "name": "John Smith",
  "state": "active",
  "locked": false,
  "avatar_url": "http://localhost:3000/uploads/user/avatar/1/index.jpg",
  "web_url": "http://localhost:3000/john_smith",
  "created_at": "2012-05-23T08:00:58Z",
  "is_admin": true,
  "bio": "",
  "location": null,
  "public_email": "john@example.com",
  "skype": "",
  "linkedin": "",
  "twitter": "",
  "discord": "",
  "website_url": "",
  "organization": "",
  "job_title": "",
  "last_sign_in_at": "2012-06-01T11:41:01Z",
  "confirmed_at": "2012-05-23T09:05:22Z",
  "theme_id": 1,
  "last_activity_on": "2012-05-23",
  "color_scheme_id": 2,
  "projects_limit": 100,
  "current_sign_in_at": "2012-06-02T06:36:55Z",
  "identities": [
    {"provider": "github", "extern_uid": "2435223452345"},
    {"provider": "bitbucket", "extern_uid": "john_smith"},
    {"provider": "google_oauth2", "extern_uid": "8776128412476123468721346"}
  ],
  "can_create_group": true,
  "can_create_project": true,
  "two_factor_enabled": true,
  "external": false,
  "private_profile": false,
  "commit_email": "john-codes@example.com",
  "current_sign_in_ip": "196.165.1.102",
  "last_sign_in_ip": "172.127.2.22",
  "namespace_id": 1,
  "created_by": null,
  "email_reset_offered_at": null,
  "note": null
}

在极狐GitLab 专业版或旗舰版中的用户还可以看到这些参数：

  • shared_runners_minutes_limit
  • extra_shared_runners_minutes_limit
  • is_auditor
  • provisioned_by_group_id
  • using_license_seat

创建用户

{{< details >}}

  • Tier: Free, Premium, Ultimate
  • Offering: 极狐GitLab 私有化部署, 极狐GitLab Dedicated

{{< /details >}}

{{< history >}}

  • 在极狐GitLab 15.3 中引入了创建审计员用户的能力。

{{< /history >}}

创建用户。

前提条件：

  • 你必须是管理员。

当你创建用户时，必须至少指定以下之一：

  • password
  • reset_password
  • force_random_password

如果 reset_password 和 force_random_password 都为 false，则 password 是必需的。

force_random_password 和 reset_password 优先于 password。此外，reset_password 和 force_random_password 可以一起使用。

{{< alert type=”note” >}}

private_profile 默认为将新用户的个人资料默认设置为私有设置的值。bio 默认为 "" 而不是 null。

{{< /alert >}}

POST /users

支持的属性：

属性 必需 描述
admin 否 用户是管理员。有效值为 true 或 false。默认为 false。
auditor 否 用户是审计员。有效值为 true 或 false。默认为 false。在极狐GitLab 15.3 中引入。仅限专业版和旗舰版。
avatar 否 用户头像的图像文件
bio 否 用户的传记
can_create_group 否 用户可以创建顶级群组 - true 或 false
color_scheme_id 否 用户的文件查看器配色方案（有关更多信息，请参阅用户偏好文档）
commit_email 否 用户的提交邮箱地址
email 是 邮箱
extern_uid 否 外部 UID
external 否 将用户标记为外部 - true 或 false（默认）
extra_shared_runners_minutes_limit 否 仅管理员可设置。为此用户设置的附加计算分钟数。仅限专业版和旗舰版。
force_random_password 否 将用户密码设置为随机值 - true 或 false（默认）
group_id_for_saml 否 已配置 SAML 的群组 ID
linkedin 否 LinkedIn
location 否 用户的位置
name 是 名称
note 否 管理员对该用户的备注
organization 否 组织名称
password 否 密码
private_profile 否 用户的个人资料是私有的 - true 或 false。默认值由设置确定。
projects_limit 否 用户可以创建的项目数
pronouns 否 用户的代词
provider 否 外部提供者名称
public_email 否 用户的公开邮箱地址
reset_password 否 发送用户密码重置链接 - true 或 false（默认）
shared_runners_minutes_limit 否 仅管理员可设置。为此用户设置的每月最大计算分钟数。可以为 nil（默认；继承系统默认值）、0（无限制）或 > 0。仅限专业版和旗舰版。
skip_confirmation 否 跳过确认 - true 或 false（默认）
skype 否 Skype ID
theme_id 否 用户的极狐GitLab 主题（有关更多信息，请参阅用户偏好文档）
twitter 否 X（以前的 Twitter）账户
discord 否 Discord 账户
username 是 用户名
view_diffs_file_by_file 否 标记用户仅能看到每页一个文件的差异
website_url 否 网站 URL

修改用户

{{< details >}}

  • Tier: Free, Premium, Ultimate
  • Offering: 极狐GitLab 私有化部署, 极狐GitLab Dedicated

{{< /details >}}

{{< history >}}

  • 在极狐GitLab 15.3 中引入了修改审计员用户的能力。

{{< /history >}}

修改现有用户。

前提条件：

  • 你必须是管理员。

email 字段是用户的主要邮箱地址。你只能将此字段更改为该用户已添加的次要邮箱地址。要向同一用户添加更多邮箱地址，请使用添加邮箱端点。

PUT /users/:id

支持的属性：

属性 必需 描述
admin 否 用户是管理员。有效值为 true 或 false。默认为 false。
auditor 否 用户是审计员。有效值为 true 或 false。默认为 false。在极狐GitLab 15.3 中引入。（默认）仅限专业版和旗舰版。
avatar 否 用户头像的图像文件
bio 否 用户的传记
can_create_group 否 用户可以创建群组 - true 或 false
color_scheme_id 否 用户的文件查看器配色方案（有关更多信息，请参阅用户偏好文档）
commit_email 否 用户的提交邮箱。设置为 _private 以使用私人提交邮箱。在极狐GitLab 15.5 中引入。
email 否 邮箱
extern_uid 否 外部 UID
external 否 将用户标记为外部 - true 或 false（默认）
extra_shared_runners_minutes_limit 否 仅管理员可设置。为此用户设置的附加计算分钟数。仅限专业版和旗舰版。
group_id_for_saml 否 已配置 SAML 的群组 ID
id 是 用户的 ID
linkedin 否 LinkedIn
location 否 用户的位置
name 否 名称
note 否 管理员对该用户的备注
organization 否 组织名称
password 否 密码
private_profile 否 用户的个人资料是私有的 - true 或 false。
projects_limit 否 每个用户可以创建的项目限制
pronouns 否 代词
provider 否 外部提供者名称
public_email 否 用户的公开邮箱（必须已验证）
shared_runners_minutes_limit 否 仅管理员可设置。为此用户设置的每月最大计算分钟数。可以为 nil（默认；继承系统默认值）、0（无限制）或 > 0。仅限专业版和旗舰版。
skip_reconfirmation 否 跳过重新确认 - true 或 false（默认）
skype 否 Skype ID
theme_id 否 用户的极狐GitLab 主题（有关更多信息，请参阅用户偏好文档）
twitter 否 X（以前的 Twitter）账户
discord 否 Discord 账户
username 否 用户名
view_diffs_file_by_file 否 标记用户仅能看到每页一个文件的差异
website_url 否 网站 URL

如果你更新用户的密码，他们将在下次登录时被迫更改密码。

返回 404 错误，即使在 409（冲突）更合适的情况下也是如此。例如，将邮箱地址重命名为已存在的邮箱地址时。

删除用户

{{< details >}}

  • Tier: Free, Premium, Ultimate
  • Offering: 极狐GitLab 私有化部署, 极狐GitLab Dedicated

{{< /details >}}

删除用户。

前提条件：

  • 你必须是管理员。

返回：

  • 如果操作成功，返回 204 No Content 状态码。
  • 如果未找到资源，返回 404。
  • 如果用户无法软删除，返回 409。
DELETE /users/:id

支持的属性：

属性 类型 必需 描述
id integer 是 用户的 ID
hard_delete boolean 否 如果为 true，则通常会被移动到幽灵用户的贡献将被删除，同时还包括仅由该用户拥有的群组。

获取你的用户状态

获取你的用户状态。

前提条件：

  • 你必须经过身份验证。
GET /user/status

示例请求：

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/user/status"

示例响应：

{
  "emoji":"coffee",
  "availability":"busy",
  "message":"I crave coffee :coffee:",
  "message_html": "I crave coffee <gl-emoji title=\"hot beverage\" data-name=\"coffee\" data-unicode-version=\"4.0\">☕</gl-emoji>",
  "clear_status_at": null
}

获取用户状态

获取用户状态。您可以在无需身份验证的情况下访问此端点。

GET /users/:id_or_username/status

支持的属性：

属性 类型 必需 描述
id_or_username string 是 要获取状态的用户的 ID 或用户名

示例请求：

curl "https://gitlab.example.com/users/<username>/status"

示例响应：

{
  "emoji":"coffee",
  "availability":"busy",
  "message":"I crave coffee :coffee:",
  "message_html": "I crave coffee <gl-emoji title=\"hot beverage\" data-name=\"coffee\" data-unicode-version=\"4.0\">☕</gl-emoji>",
  "clear_status_at": null
}

设置你的用户状态

设置你的用户状态。

前提条件：

  • 你必须经过身份验证。
PUT /user/status
PATCH /user/status

支持的属性：

属性 类型 必需 描述
emoji string 否 用作状态的表情符号的名称。如果省略，则使用 speech_balloon。表情符号名称可以是Gemojione 索引中指定的名称之一。
message string 否 设置为状态的消息。它还可以包含表情符号代码。不能超过 100 个字符。
clear_status_after string 否 在给定的时间间隔后自动清理状态，允许的值为：30_minutes、3_hours、8_hours、1_day、3_days、7_days、30_days

PUT 和 PATCH 的区别：

  • 使用 PUT 时，任何未传递的参数都将设置为 null，因此被清除。
  • 使用 PATCH 时，任何未传递的参数都会被忽略。显式传递 null 以清除字段。

示例请求：

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --data "clear_status_after=1_day" --data "emoji=coffee" \
     --data "message=I crave coffee" "https://gitlab.example.com/api/v4/user/status"

示例响应：

{
  "emoji":"coffee",
  "message":"I crave coffee",
  "message_html": "I crave coffee",
  "clear_status_at":"2021-02-15T10:49:01.311Z"
}

获取你的用户偏好设置

获取你的用户偏好设置。

前提条件：

  • 你必须经过身份验证。
GET /user/preferences

示例响应：

{
  "id": 1,
  "user_id": 1,
  "view_diffs_file_by_file": true,
  "show_whitespace_in_diffs": false,
  "pass_user_identities_to_ci_jwt": false
}

更新您的用户偏好设置

更新您的用户偏好设置。

先决条件：

  1. 您必须经过身份验证。
PUT /user/preferences

{
  "id": 1,
  "user_id": 1,
  "view_diffs_file_by_file": true,
  "show_whitespace_in_diffs": false,
  "pass_user_identities_to_ci_jwt": false
}

支持的属性：

属性 必需 描述
view_diffs_file_by_file 是 标志指示用户每页仅查看一个文件的差异。
show_whitespace_in_diffs 是 标志指示用户在差异中查看空白更改。
pass_user_identities_to_ci_jwt 是 标志指示用户将他们的外部身份传递为 CI 信息。此属性不包含足够的信息来识别或授权用户在外部系统中。该属性是极狐GitLab 内部的，不能传递给第三方服务。有关更多信息和示例，请参见令牌负载。

为自己上传头像

{{< history >}}

  • 引入于极狐GitLab 17.0。

{{< /history >}}

为自己上传头像。

先决条件：

  1. 您必须经过身份验证。
PUT /user/avatar

支持的属性：

属性 类型 必需 描述
avatar 字符串 是 要上传的文件。理想的图像尺寸是 192 x 192 像素。允许的最大文件大小为 200 KiB。

要从您的文件系统上传头像，请使用 --form 参数。这会导致 cURL 使用标头 Content-Type: multipart/form-data 发布数据。 file= 参数必须指向您文件系统上的图像文件，并以 @ 为前缀。例如：

请求示例：

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
     --form "avatar=@avatar.png" \
     --url "https://gitlab.example.com/api/v4/user/avatar"

响应示例：

{
  "avatar_url": "http://gdk.test:3000/uploads/-/system/user/avatar/76/avatar.png",
}

返回：

  1. 成功时返回 200。
  2. 对于超过 200 KiB 的文件大小返回 400 Bad Request。

获取您分配的议题、合并请求和评审的数量

获取您分配的议题、合并请求和评审的数量。

先决条件：

  1. 您必须经过身份验证。

支持的属性：

属性 类型 描述
assigned_issues 数字 打开并分配给当前用户的议题数量。
assigned_merge_requests 数字 活跃并分配给当前用户的合并请求数量。
merge_requests 数字 在极狐GitLab 13.8 中弃用。由 assigned_merge_requests 替代。
review_requested_merge_requests 数字 当前用户被请求评审的合并请求数量。
todos 数字 当前用户的待办事项数量。 
GET /user_counts

请求示例：

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/user_counts"

响应示例：

{
  "merge_requests": 4,
  "assigned_issues": 15,
  "assigned_merge_requests": 11,
  "review_requested_merge_requests": 0,
  "todos": 1
}

获取用户的项目、群组、议题和合并请求的数量

获取用户的以下数量列表：

  • 项目。
  • 群组。
  • 议题。
  • 合并请求。

管理员可以查询任何用户，但非管理员只能查询自己。

GET /users/:id/associations_count

支持的属性：

属性 类型 必需 描述
id 整数 是 用户的 ID

响应示例：

{
  "groups_count": 2,
  "projects_count": 3,
  "issues_count": 8,
  "merge_requests_count": 5
}

列出用户的活动

{{< details >}}

  • 层级：基础版，专业版，旗舰版
  • 提供：极狐GitLab 私有化部署，极狐GitLab 专属

{{< /details >}}

先决条件：

  1. 您必须是管理员才能查看具有私人资料的用户的活动。

获取具有公共资料的用户的最后活动日期，从最旧到最新排序。

更新用户事件时间戳（last_activity_on 和 current_sign_in_at）的活动是：

  • Git HTTP/SSH 活动（如克隆、推送）
  • 用户登录极狐GitLab
  • 用户访问与仪表板、项目、议题和合并请求相关的页面
  • 用户使用 API
  • 用户使用 GraphQL API

默认情况下，它显示最近 6 个月内具有公共资料的用户的活动，但可以通过使用 from 参数进行修改。

GET /user/activities

支持的属性：

属性 类型 必需 描述
from 字符串 否 格式为 YEAR-MM-DD 的日期字符串。例如，2016-03-11。默认为 6 个月前。

请求示例：

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/user/activities"

响应示例：

[
  {
    "username": "user1",
    "last_activity_on": "2015-12-14",
    "last_activity_at": "2015-12-14"
  },
  {
    "username": "user2",
    "last_activity_on": "2015-12-15",
    "last_activity_at": "2015-12-15"
  },
  {
    "username": "user3",
    "last_activity_on": "2015-12-16",
    "last_activity_at": "2015-12-16"
  }
]

last_activity_at 已弃用。请使用 last_activity_on。

列出用户所属的项目和群组

{{< details >}}

  • 层级：基础版，专业版，旗舰版
  • 提供：私有化部署

{{< /details >}}

先决条件：

  1. 您必须是管理员。

列出用户所属的所有项目和群组。

返回成员关系的 source_id、source_name、source_type 和 access_level。来源可以是 Namespace 类型（代表一个群组）或 Project。响应仅代表直接成员关系。继承的成员关系，例如在子群组中，不包括在内。访问级别由整数值表示。有关详细信息，请阅读有关 访问级别值 的含义。

GET /users/:id/memberships

支持的属性：

属性 类型 必需 描述
id 整数 是 指定用户的 ID
type 字符串 否 按类型过滤成员关系。可以是 Project 或 Namespace

请求示例：

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/:user_id/memberships"

响应示例：

[
  {
    "source_id": 1,
    "source_name": "Project one",
    "source_type": "Project",
    "access_level": "20"
  },
  {
    "source_id": 3,
    "source_name": "Group three",
    "source_type": "Namespace",
    "access_level": "20"
  }
]

返回：

  1. 成功时返回 200 OK。
  2. 如果找不到用户，返回 404 User Not Found。
  3. 当请求者不是管理员时，返回 403 Forbidden。
  4. 当请求的类型不受支持时，返回 400 Bad Request。

禁用用户的两因素身份验证

{{< details >}}

  • 层级：基础版，专业版，旗舰版
  • 提供：极狐GitLab 私有化部署，极狐GitLab 专属

{{< /details >}}

{{< history >}}

  • 引入于极狐GitLab 15.2。

{{< /history >}}

先决条件：

  1. 您必须是管理员。

为指定用户禁用两因素身份验证（2FA）。

管理员无法通过 API 禁用其自己的用户帐户或其他管理员的 2FA。相反，他们可以通过 使用 Rails 控制台 禁用管理员的 2FA。

PATCH /users/:id/disable_two_factor

支持的属性：

属性 类型 必需 描述
id 整数 是 用户的 ID

请求示例：

curl --request PATCH --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/1/disable_two_factor"

返回：

  1. 成功时返回 204 No content。
  2. 如果指定用户未启用两因素身份验证，返回 400 Bad request。
  3. 如果不是以管理员身份认证，返回 403 Forbidden。
  4. 如果找不到用户，返回 404 User Not Found。

创建与用户关联的 Runner

{{< details >}}

  • 层级：基础版，专业版，旗舰版
  • 提供：JihuLab.com，极狐GitLab 私有化部署，极狐GitLab 专属

{{< /details >}}

创建与当前用户关联的 Runner。

先决条件：

  1. 您必须是管理员或具有目标命名空间或项目的所有者角色。
  2. 对于 instance_type，您必须是极狐GitLab 实例的管理员。
  3. 对于具有所有者角色的 group_type 或 project_type，管理员不得启用 限制 Runner 注册。
  4. 具有 create_runner 范围的访问令牌。

请务必复制或保存响应中的 token，该值无法再次检索。

POST /user/runners

支持的属性：

属性 类型 必需 描述
runner_type 字符串 是 指定 Runner 的范围；instance_type、group_type 或 project_type。
group_id 整数 否 Runner 创建所在群组的 ID。如果 runner_type 是 group_type，则必需。
project_id 整数 否 Runner 创建所在项目的 ID。如果 runner_type 是 project_type，则必需。
description 字符串 否 Runner 的描述。
paused 布尔值 否 指定 Runner 是否应忽略新作业。
locked 布尔值 否 指定 Runner 是否应锁定当前项目。
run_untagged 布尔值 否 指定 Runner 是否应处理未标记的作业。
tag_list 字符串数组 否 Runner 标签列表。
access_level 字符串 否 Runner 的访问级别；not_protected 或 ref_protected。
maximum_timeout 整数 否 限制 Runner 可以运行作业的时间（以秒为单位）的最大超时。
maintenance_note 字符串 否 Runner 的自由格式维护笔记（1024 个字符）。

请求示例：

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "runner_type=instance_type" \
     "https://gitlab.example.com/api/v4/user/runners"

响应示例：

{
    "id": 9171,
    "token": "<access-token>",
    "token_expires_at": null
}

从用户中删除身份验证身份

{{< details >}}

  • 层级：基础版，专业版，旗舰版
  • 提供：私有化部署

{{< /details >}}

使用与身份关联的提供者名称删除用户的身份验证身份。

先决条件：

  1. 您必须是管理员。
DELETE /users/:id/identities/:provider

支持的属性：

属性 类型 必需 描述
id 整数 是 用户的 ID
provider 字符串 是 外部提供者名称

创建支持 PIN

{{< details >}}

  • 层级：基础版，专业版，旗舰版
  • 提供：JihuLab.com，极狐GitLab 私有化部署，极狐GitLab 专属

{{< /details >}}

{{< history >}}

  • 引入于极狐GitLab 17.8。

{{< /history >}}

为您的用户帐户创建支持 PIN。该 PIN 在创建后七天过期。极狐GitLab 支持可能会要求您提供此 PIN 来验证您的身份。

先决条件：

  1. 您必须经过身份验证。
POST /user/support_pin

请求示例：

curl --request POST |
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/user/support_pin"

响应示例：

{
  "pin":"123456",
  "expires_at":"2025-02-27T22:06:57Z"
}

获取支持 PIN 的详细信息

{{< details >}}

  • 层级：基础版，专业版，旗舰版
  • 提供：JihuLab.com，私有化部署

{{< /details >}}

{{< history >}}

  • 引入于极狐GitLab 17.8。

{{< /history >}}

获取您的帐户的支持 PIN 的详细信息。极狐GitLab 支持可能会要求您提供此 PIN 来验证您的身份。

先决条件：

  1. 您必须经过身份验证。
GET /user/support_pin

请求示例：

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/user/support_pin"

响应示例：

{
  "pin":"123456",
  "expires_at":"2025-02-27T22:06:57Z"
}

获取用户的支持 PIN

{{< details >}}

  • 层级：基础版，专业版，旗舰版
  • 提供：JihuLab.com，极狐GitLab 私有化部署，极狐GitLab 专属

{{< /details >}}

{{< history >}}

  • 引入于极狐GitLab 17.8。

{{< /history >}}

获取指定用户的支持 PIN 的详细信息。极狐GitLab 支持可能会要求您提供此 PIN 来验证您的身份。

先决条件：

  1. 您必须是管理员。
GET /users/:id/support_pin

请求示例：

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/1234/support_pin"

响应示例：

{
  "pin":"123456",
  "expires_at":"2025-02-27T22:06:57Z"
}

支持的属性：

属性 类型 必需 描述
id 整数 是 用户帐户的 ID