Help us learn about your current experience with the documentation. Take the survey.

邀请 API

  • 版本：Free, Premium, Ultimate
  • 产品形态：GitLab.com, GitLab Self-Managed, GitLab Dedicated

使用此 API 管理邀请，并将用户添加到 群组 或 项目 中。

有效的访问级别

要发送邀请，您必须拥有您要发送邮件的项目或群组的访问权限。 有效的访问级别在 Gitlab::Access 模块中定义：

  • 无访问权限 (0)
  • 最小访问权限 (5)
  • 访客 (10)
  • 规划者 (15)
  • 报告者 (20)
  • 开发者 (30)
  • 维护者 (40)
  • 所有者 (50)

向群组或项目添加成员

添加一个新成员。您可以指定用户 ID 或通过电子邮件邀请用户。

前提条件：

POST /groups/:id/invitations
POST /projects/:id/invitations
属性 类型 是否必需 描述
id integer/string 是 项目或群组的 ID 或 URL 编码路径
email string 是（如果未提供 user_id） 新成员的电子邮件，或多个以逗号分隔的电子邮件地址。
user_id integer/string 是（如果未提供 email） 新成员的 ID，或多个以逗号分隔的 ID。
access_level integer 是 一个有效的访问级别
expires_at string 否 格式为 YEAR-MONTH-DAY 的日期字符串
invite_source string 否 启动成员创建流程的邀请来源。请参阅此议题。
member_role_id integer 否 将新成员分配到提供的自定义角色。（在 GitLab 16.6 中引入）。仅限 Ultimate 版本。 
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/:id/invitations" \
  --data "email=test@example.com&user_id=1&access_level=30"
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/:id/invitations" \
  --data "email=test@example.com&user_id=1&access_level=30"

示例响应：

当所有邮件均成功发送时：

{  "status":  "success"  }

当发送邮件时出现任何错误时：

{
  "status": "error",
  "message": {
               "test@example.com": "邀请邮件已被使用",
               "test2@example.com": "用户已存在于源中",
               "test_username": "访问级别未包含在列表中"
             }
}

要启用 Manage non-billable promotions（管理非计费升级）， 您必须首先启用 enable_member_promotion_management 应用设置。

示例响应：

{
  "queued_users": {
    "username_1": "请求已排队等待管理员批准。"
  },
  "status": "success"
}

列出群组或项目的所有待处理邀请

获取经过身份验证的用户可见的受邀群组或项目成员列表。 仅返回直接成员的邀请，而不包括通过继承的上级群组获得的邀请。

此函数使用分页参数 page 和 per_page 来限制成员列表。

GET /groups/:id/invitations
GET /projects/:id/invitations
属性 类型 是否必需 描述
id integer/string 是 项目或群组的 ID 或 URL 编码路径
page integer 否 要检索的页面
per_page integer 否 每页返回的成员邀请数量
query string 否 用于通过邀请电子邮件搜索受邀成员的查询字符串。查询文本必须与电子邮件地址完全匹配。如果为空，则返回所有邀请。 
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/:id/invitations?query=member@example.org"
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/:id/invitations?query=member@example.org"

示例响应：

 [
   {
     "id": 1,
     "invite_email": "member@example.org",
     "created_at": "2020-10-22T14:13:35Z",
     "access_level": 30,
     "expires_at": "2020-11-22T14:13:35Z",
     "user_name": "Raymond Smith",
     "created_by_name": "Administrator"
   },
]

更新群组或项目的邀请

更新待处理邀请的访问级别或访问到期日期。

PUT /groups/:id/invitations/:email
PUT /projects/:id/invitations/:email
属性 类型 是否必需 描述
id integer/string 是 项目或群组的 ID 或 URL 编码路径。
email string 是 之前发送邀请的电子邮件地址。
access_level integer 否 一个有效的访问级别（默认值：30，即开发者角色）。
expires_at string 否 ISO 8601 格式 (YYYY-MM-DDTHH:MM:SSZ) 的日期字符串。 
curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/55/invitations/email@example.org?access_level=40"
curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/55/invitations/email@example.org?access_level=40"

示例响应：

{
  "expires_at": "2012-10-22T14:13:35Z",
  "access_level": 40,
}

删除群组或项目的邀请

通过电子邮件地址删除待处理的邀请。

DELETE /groups/:id/invitations/:email
DELETE /projects/:id/invitations/:email
属性 类型 是否必需 描述
id integer/string 是 项目或群组的 ID 或 URL 编码路径
email string 是 之前发送邀请的电子邮件地址 
curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/55/invitations/email@example.org"
curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/55/invitations/email@example.org"
  • 成功时返回 204 且无内容。
  • 如果无权删除邀请，则返回 403 禁止访问。
  • 如果有权访问但未找到该电子邮件地址的邀请，则返回 404 未找到。
  • 如果请求有效但无法删除邀请，则返回 409 冲突。