项目组 | 帮助文档 - 工蜂合作伙伴版

# 项目组

如果使用 project_full_path，确保 project_full_path 编码过，例子：/api/v3/projects/tencent/code--> /api/v3/projects/tencent%2Fcode (/ 编码 %2F)

# 组权限

组/项目的权限access_level包括：

GUEST = 10
FOLLOWER = 15
REPORTER = 20
DEVELOPER = 30
MASTER = 40
OWNER = 50

# 新建项目组

创建一个新的项目组。仅对有权限创建项目组的用户可用。

POST /api/v3/groups

参数：

参数	类型	描述
name	string	项目组的名字
path	string	项目组的路径
parent_id	integer	父目录 namespaceid 注：新建 subgroup 需传
description	string	关于这个项目组的描述

返回值：

[
  {
    "id": 98489,
    "name": "git_01subgroup",
    "path": "git_01subgroup",
    "description": "",
    "avatar_url": "https://git.tencent.com/assets/images/avatar/no_group_avatar.png",
    "full_name": "git_01rootgroup/git_01subgroup",
    "full_path": "git_01rootgroup/git_01subgroup",
    "web_url": "https://git.tencent.com/groups/git_01rootgroup/git_01subgroup",
    "parent_id": 98488
  }
]

# 编辑项目组

更新项目组的名称和描述。（暂不支持更新项目组路径）

PUT /api/v3/groups/:id

参数：

参数	类型	描述
id	integer	用户的项目组 ID 或者项目组全路径namespace_full_path
name	string	项目组的名字
description	string	关于这个项目组的描述

返回值：

[
  {
    "id": 98488,
    "name": "git_01rootgroup",
    "path": "git_01rootgroup",
    "description": "第一个 subgroup 子目录",
    "avatar_url": "https://git.tencent.com/assets/images/avatar/no_group_avatar.png",
    "full_name": "git_01rootgroup",
    "full_path": "git_01rootgroup",
    "web_url": "https://git.tencent.com/groups/git_01rootgroup",
    "parent_id": null
  }
]

# 删除项目组

删除一个指定的项目组。

DELETE /api/v3/groups/:id

参数：

参数	类型	描述
id	integer	用户的项目组 ID 或者项目组全路径namespace_full_path

返回值：

200或相关状态码

# 获取项目组列表

获取项目组列表。(作为用户获取的是我的项目组，作为管理者获取的是所有的项目组)

GET /api/v3/groups

参数：

参数	类型	描述
owned	boolean（可选）	若为 true 则只返回 owner 为当前用户的 group
min_access_level	integer（可选）	指定最小访问级别，返回的 group 列表中，当前用户的 group 访问级别大于或者等于指定值
created_by_me	boolean（可选）	项目组创建者过滤，仅当前用户创建`true` 仅非当前用户创建`false` 默认不过滤(不传递参数)
exclude_org_group	boolean（可选）	组织架构授权过滤，排除组织架构授权`true` 默认不过滤(false或不传递参数)
page	integer（可选）	分页 (默认值:`1`)
per_page	integer（可选）	默认页面大小 (默认值 `20`，最大值： `100`)

返回值：

[
  {
    "id": 95698,
    "name": "git_01subgroup.1",
    "path": "git_01subgroup.1",
    "description": "",
    "avatar_url": "https://git.tencent.com/assets/images/avatar/no_group_avatar.png",
    "full_name": "git_01rootsubgroup/git_01subgroup.1",
    "full_path": "git_01subgroup/git_01subgroup.1",
    "web_url": "https://git.tencent.com/groups/git_01subgroup/git_01subgroup.1",
    "parent_id": 95696
  }
]

你能够通过名称或者路径查询项目组，如下。

# 获取项目组 subgroup 列表

获取项目组 subgroup 列表

GET /api/v3/groups/:id/subgroups

参数：

参数	类型	描述
owned	boolean（可选）	若为 true 则只返回 owner 为当前用户的 group
min_access_level	integer（可选）	指定最小访问级别，返回的 group 列表中，当前用户的 group 访问级别大于或者等于指定值
created_by_me	boolean（可选）	项目组创建者过滤，仅当前用户创建`true` 仅非当前用户创建`false` 默认不过滤(不传递参数)
exclude_org_group	boolean（可选）	组织架构授权过滤，排除组织架构授权`true` 默认不过滤(false或不传递参数)
page	integer（可选）	分页 (默认值:`1`)
per_page	integer（可选）	默认页面大小 (默认值 `20`，最大值： `100`)

返回值：

[
  {
    "id": 95698,
    "name": "git_01subgroup.1",
    "path": "git_01subgroup.1",
    "description": "",
    "avatar_url": "https://git.tencent.com/assets/images/avatar/no_group_avatar.png",
    "full_name": "git_01subgroup.1",
    "full_path": "git_01subgroup.1",
    "web_url": "https://git.tencent.com/groups/git_01subgroup.1",
    "parent_id": 95696
  },
  {
    "id": 98363,
    "name": "testgroup1.1",
    "path": "git_01subgroup.2",
    "description": "subgroup_info",
    "avatar_url": "https://git.tencent.com/assets/images/avatar/no_group_avatar.png",
    "full_name": "git_01rootsubgroup/testgroup1.1",
    "full_path": "git_01subgroup/git_01subgroup.2",
    "web_url": "https://git.tencent.com/groups/git_01subgroup/git_01subgroup.2",
    "parent_id": 95696
  }
]

# 搜索项目组

通过名称或者路径查询所有匹配的项目组。

GET /api/v3/groups

参数：

参数	类型	描述
search	string（可选）	默认有权限的所有项目组
created_by_me	boolean（可选）	项目组创建者过滤，仅当前用户创建`true` 仅非当前用户创建`false` 默认不过滤(不传递参数)
exclude_org_group	boolean（可选）	组织架构授权过滤，排除组织架构授权`true` 默认不过滤(false或不传递参数)
page	integer（可选）	分页 (默认值:`1`)
per_page	integer（可选）	默认页面大小 (默认值 `20`，最大值： `100`)

返回值：

[
  {
    "id": 98363,
    "name": "testgroup1.1",
    "path": "git_01subgroup.2",
    "description": "subgroup_info",
    "avatar_url": "https://git.tencent.com/assets/images/avatar/no_group_avatar.png",
    "full_name": "git_01rootsubgroup/testgroup1.1",
    "full_path": "git_01subgroup/git_01subgroup.2",
    "web_url": "https://git.tencent.com/groups/git_01subgroup/git_01subgroup.2",
    "parent_id": 95696
  }
]

# 转移项目组

把当前项目组转移到指定项目组下

项目组下有 SVN 项目暂不支持转移

POST /api/v3/groups/:id/transfer/:group_id

参数：

参数	类型	描述
id	integer	用户的项目组 ID 或者项目组全路径namespace_full_path
group_id	integer	转移目标项目组 ID，输入`-1` 则表示设置为根项目组

返回值：

[
  {
    "id": 98363,
    "name": "testgroup1.1",
    "path": "git_01subgroup.2",
    "description": "subgroup_info",
    "avatar_url": "https://git.tencent.com/assets/images/avatar/no_group_avatar.png",
    "full_name": "git_01rootsubgroup/testgroup1.1",
    "full_path": "git_01subgroup/git_01subgroup.2",
    "web_url": "https://git.tencent.com/groups/git_01subgroup/git_01subgroup.2",
    "parent_id": 95696
  }
]

# 用户组

# 获取用户组列表

获取当前项目组下直接定义的用户组列表。

GET /api/v3/groups/:id/user_groups

参数：

参数	类型	描述
id	integer	项目组 ID 或者项目组全路径 namespace_full_path
page	integer（可选）	分页 (默认`1`)
per_page	integer（可选）	默认页面大小 (默认 `20`，最大`100`)

返回值：

[
  {
    "description": "",
    "id": 1,
    "name": "x",
    "org_bindings": [
      {
        "id": 10001,
        "name": "xxx",
        "org_path": "xxxxxx 事业群/xxxxx 部/xxxx 等",
        "enabled": true
      }
    ],
    "users": [
      {
        "avatar_url": "https://git.tencent.com/uploads/user/avatar/1/2c37c36551d84f9185a3d8cf04620981.gif",
        "id": 1,
        "name": "xx",
        "state": "active",
        "username": "xxx",
        "web_url": "http://git.tencent.com/u/xxx"
      }
    ]
  }
]

# 新增用户组

增加一个用户组。

POST /api/v3/groups/:id/user_groups

参数：

参数	类型	描述
id	integer	项目组 ID 或者项目组全路径 namespace_full_path
name	string	用户组名称
description	string（可选）	用户组的描述
usernames	array of string（可选）	用户组的成员
org_ids	array of integer（可选）	用户组绑定的组织架构

返回值：

{
  "description": "",
  "id": 1,
  "name": "x",
  "org_bindings": [
    {
      "id": 10001,
      "name": "xxx",
      "org_path": "xxxxxx 事业群/xxxxx 部/xxxx 等",
      "enabled": true
    }
  ],
  "users": [
    {
      "avatar_url": "https://git.tencent.com/uploads/user/avatar/1/2c37c36551d84f9185a3d8cf04620981.gif",
      "id": 1,
      "name": "xx",
      "state": "active",
      "username": "xxx",
      "web_url": "http://git.tencent.com/u/xxx"
    }
  ]
}

# 修改用户组

更新一个用户组。

PUT /api/v3/groups/:id/user_groups/:user_group_id

参数：

参数	类型	描述
id	integer	项目组 ID 或者项目组全路径 namespace_full_path
user_group_id	integer	用户组 ID
name	string（可选）	用户组名称
description	string（可选）	用户组的描述
delete_usernames	array of string（可选）	删除的成员
add_usernames	array of string（可选）	新增的成员
delete_org_ids	array of integer（可选）	删除的组织架构绑定
add_org_ids	array of integer（可选）	新增的组织架构绑定

返回值：

{
  "description": "",
  "id": 1,
  "name": "x",
  "org_bindings": [
    {
      "id": 10001,
      "name": "xxx",
      "org_path": "xxxxxx 事业群/xxxxx 部/xxxx 等",
      "enabled": true
    }
  ],
  "users": [
    {
      "avatar_url": "https://git.tencent.com/uploads/user/avatar/1/2c37c36551d84f9185a3d8cf04620981.gif",
      "id": 1,
      "name": "xx",
      "state": "active",
      "username": "xxx",
      "web_url": "http://git.tencent.com/u/xxx"
    }
  ]
}

# 删除用户组

删除一个用户组。

DELETE /api/v3/groups/:id/user_groups/:user_group_id

参数：

参数	类型	描述
id	integer	项目组 ID 或者项目组全路径 namespace_full_path
user_group_id	integer	用户组 ID

返回值：

200或相关状态码

# 项目组成员

项目组成员访问级别

项目组的访问级别定义如下：

GUEST     = 10
FOLLOWER  = 15
REPORTER  = 20
DEVELOPER = 30
MASTER    = 40
OWNER     = 50

# 获取项目组成员列表

获取认证用户可见的项目组成员列表。

GET /api/v3/groups/:id/members

参数：

参数	类型	描述
id	integer	项目组 ID 或者项目组全路径 namespace_full_path
page	integer（可选）	分页 (默认:`1`)
per_page	integer（可选）	默认页面大小 (默认 `20`，最大： `100`)

返回值：

[
  {
    "id": 1,
    "username": "xiaoshu",
    "web_url": "https://git.tencent.com/u/xiaoshu",
    "name": "xiaoshu",
    "state": "active",
    "avatar_url": "https://git.tencent.com/uploads/user/avatar/1/2c37c36551d84f9185a3d8cf04620981.gif",
    "access_level": 50,
    "expires_at": null
  },
  {
    "id": 2,
    "username": "long",
    "web_url": "https://git.tencent.com/u/long",
    "name": "long",
    "state": "active",
    "avatar_url": "https://git.tencent.com/uploads/user/avatar/2/2c32c36551d84f9185a3d8cf04620981.gif",
    "access_level": 30,
    "expires_at": null
  }
]

# 获取项目组有权限的成员列表

获取项目组有权限的成员列表。

GET /api/v3/groups/:id/members/all

参数：

参数	类型	描述
id	integer	项目组 ID 或者项目组全路径 namespace_full_path
page	integer（可选）	分页 (默认:`1`)
per_page	integer（可选）	默认页面大小 (默认 `20`，最大： `100`)

返回值：

[
  {
    "id": 1,
    "username": "xiaoshu",
    "web_url": "https://git.tencent.com/u/xiaoshu",
    "name": "xiaoshu",
    "state": "active",
    "avatar_url": "https://git.tencent.com/uploads/user/avatar/1/2c37c36551d84f9185a3d8cf04620981.gif",
    "access_level": 50,
    "expires_at": null
  },
  {
    "id": 2,
    "username": "long",
    "web_url": "https://git.tencent.com/u/long",
    "name": "long",
    "state": "active",
    "avatar_url": "https://git.tencent.com/uploads/user/avatar/2/2c32c36551d84f9185a3d8cf04620981.gif",
    "access_level": 30,
    "expires_at": null
  }
]

# 增加项目组成员

增加一个项目组成员。

POST /api/v3/groups/:id/members

参数：

参数	类型	描述
id	integer	项目组 ID 或者项目组全路径 namespace_full_path
user_id	integer	添加用户的 ID
access_level	integer	项目访问级别
expires_at	yyyy-MM-ddZ(可选）	用户权限到期时间，例如 2019-03-25+0000 或 2019-03-25+0800
reason	string（可选）	操作理由备注，xxxx

返回值：

{
  "id": 2526,
  "username": "bili",
  "web_url": "https://git.tencent.com/u/bili",
  "name": "bili",
  "state": "active",
  "avatar_url": "https://git.tencent.com/uploads/user/avatar/2526/2c37c36551d84f9185a3d8cf04620981.gif",
  "access_level": 40,
  "expires_at": "2019-09-25T16:00:00+0000"
}

# 修改项目组成员

更新一个项目组成员的访问权限。

PUT /api/v3/groups/:id/members/:user_id

参数：

参数	类型	描述
id	integer	项目组 ID 或者项目组全路径 namespace_full_path
user_id	integer	项目组成员的 ID
access_level	integer	项目访问级别
expires_at	yyyy-MM-ddZ(可选）	用户权限到期时间，例如 2019-03-25+0000 或 2019-03-25+0800
reason	string（可选）	操作理由备注，xxxx

返回值：

{
  "id": 2526,
  "username": "bili",
  "web_url": "https://git.tencent.com/u/bili",
  "name": "bili",
  "state": "active",
  "avatar_url": "https://git.tencent.com/uploads/user/avatar/2526/2c37c36551d84f9185a3d8cf04620981.gif",
  "access_level": 10,
  "expires_at": null
}

# 移除一个项目组成员

移除一个指定的项目组成员。

DELETE /api/v3/groups/:id/members/:user_id

参数：

参数	类型	描述
id	integer	项目组 ID 或者项目组全路径 namespace_full_path
user_id	integer	项目组成员的 ID

返回值：


200或相关状态码

# 获取项目组指定成员信息

获取项目组指定成员信息。

GET /api/v3/groups/:id/members/:user_id

参数：

参数	类型	描述
id	integer	项目组 ID 或者项目组全路径 namespace_full_path
user_id	integer	用户 ID

返回值：

{
  "id": 1,
  "username": "xiaoshu",
  "web_url": "https://git.tencent.com/u/xiaoshu",
  "name": "xiaoshu",
  "state": "active",
  "avatar_url": "https://git.tencent.com/uploads/user/avatar/1/2c37c36551d84f9185a3d8cf04620981.gif",
  "access_level": 50,
  "expires_at": null
}

# 获取项目组指定有权限的成员信息

获取项目组指定有权限的成员信息。

GET /api/v3/groups/:id/members/all/:user_id

参数：

参数	类型	描述
id	integer	项目组 ID 或者项目组全路径 namespace_full_path
user_id	integer	用户 ID

返回值：

{
  "id": 1,
  "username": "xiaoshu",
  "web_url": "https://git.tencent.com/u/xiaoshu",
  "name": "xiaoshu",
  "state": "active",
  "avatar_url": "https://git.tencent.com/uploads/user/avatar/1/2c37c36551d84f9185a3d8cf04620981.gif",
  "access_level": 50,
  "expires_at": null
}

# 获取项目组的详细信息以及项目组下所有项目

获取对指定项目组的详细信息，以及项目组下所有项目。

GET /api/v3/groups/:id

参数：

参数	类型	描述
id	integer	项目组 ID 或者项目组全路径 namespace_full_path
include_subgroups	boolean	是否包含 subgroup 项目`true` 表示包含 (默认 `false`)

{
  "id": 556435,
  "name": "test",
  "path": "test",
  "description": "",
  "avatar_url": "https://git.tencent.com/assets/images/avatar/no_group_avatar.png",
  "full_name": "kong",
  "full_path": "kong",
  "web_url": "https://git.tencent.com/groups/test",
  "parent_id": null,
  "projects": [],
  "sub_projects": []
}

# 获取受邀项目列表

返回项目组下的受邀项目列表，支持搜索、分页

GET /api/v3/groups/:id/projects/shared

参数：

参数	类型	描述
id	integer	项目组 ID 或者项目组全路径 namespace_full_path
search	string（可选）	搜索条件，模糊匹配`path`,`name`
order_by	string（可选）	排序字段，允许按 `id`,`name`,`path`,`created_at`,`updated_at`,`last_activity_at`排序（默认`created_at`）
sort	string（可选）	排序方式，允许`asc`,`desc`（默认 `desc`）
page	integer（可选）	页数（默认值：`1`）
per_page	integer（可选）	默认页面大小（默认值：`20`，最大值：`100`）

返回值：

[
  {
    "path_with_namespace": "namespace/repo1"
  },
  {
    "path_with_namespace": "namespace/repo2"
  }
]

# 项目组访问令牌 (group_access_token)

项目组访问令牌会自动在项目组下生成一个 bot 用户，令牌归属到 bot 用户名下，使用该令牌执行的操作均视为 bot 用户行为。使用项目组访问令牌进行认证的方式与个人访问令牌类型，请参考 Personal_access_token 文档。

# 创建项目组访问令牌

创建一个项目组访问令牌

POST  /api/v3/groups/:group_id/access_tokens

参数：

参数	类型	描述
group_id	integer	项目组 ID 或者项目组全路径 namespace_full_path
name	string	令牌名称，长度在 1-50 个字符
access_level	Integer	令牌角色权限
scopes	array of string	令牌范围，可选值：api,read_repository,write_repository
expires_at	yyyy-MM-ddThh:mm:ssZ(可选)	令牌过期时间，默认没有过期时间，如需指定需要大于当前时间，比如：2025-05-08T00:00:00+0000

返回值：

{
  "id": 37,
  "name": "tokenName",
  "accessLevel": 50,
  "expiresAt": "2025-05-27T00:00:00+0000",
  "scopes": [
    "api"
  ],
  "token": "wd0Y4p7wKTd0I9MGp5lE",
  "state": "available",
  "taskState": "no task",
  "createdAt": "2024-05-27T03:55:02+0000",
  "updatedAt": "2024-05-27T03:55:02+0000"
}

令牌字段token只会在创建完之后返回，需要调用方自己保存。

# 删除项目组访问令牌

删除一个项目组访问令牌

DELETE  /api/v3/groups/:group_id/access_tokens/:id

参数：

参数	类型	描述
group_id	integer	项目组 ID 或者项目组全路径 namespace_full_path
id	integer	令牌 id

返回值：

200或相关状态码

# 修改项目组访问令牌

修改一个项目组访问令牌

PUT  /api/v3/groups/:group_id/access_tokens/:id

参数：

参数	类型	描述
group_id	integer	项目组 ID 或者项目组全路径 namespace_full_path
id	integer	令牌 id
name	String（可选）	令牌名称，长度在 1-50 个字符
access_level	Integer（可选）	令牌角色权限
scopes	array of string（可选）	令牌范围，可选值：api,read_repository,write_repository
expires_at	yyyy-MM-ddThh:mm:ssZ(可选)	令牌过期时间，如需指定需要大于当前时间，比如：2025-05-08T00:00:00+0000

返回值：

200或相关状态码

# 查看项目组访问令牌

查看一个项目组访问令牌

GET  /api/v3/groups/:group_id/access_tokens/:id

参数：

参数	类型	描述
group_id	integer	项目组 ID 或者项目组全路径 namespace_full_path
id	integer	令牌 id

返回值：

{
  "id": 37,
  "name": "tokenName",
  "accessLevel": 50,
  "expiresAt": "2025-05-27T00:00:00+0000",
  "scopes": [
    "api"
  ],
  "state": "available",
  "taskState": "no task",
  "createdAt": "2024-05-27T03:55:03+0000",
  "updatedAt": "2024-05-27T03:55:03+0000"
}

# 查看项目组访问令牌列表

查看项目组下所有访问令牌

GET  /api/v3/groups/:group_id/access_tokens

参数：

参数	类型	描述
group_id	integer	项目组 ID 或者项目组全路径 namespace_full_path

返回值：

[
  {
    "id": 7,
    "name": "tokenName1",
    "accessLevel": 10,
    "expiresAt": null,
    "scopes": [
      "api"
    ],
    "state": "available",
    "taskState": "no task",
    "createdAt": "2024-05-16T11:33:23+0000",
    "updatedAt": "2024-05-16T11:33:48+0000"
  },
  {
    "id": 19,
    "name": "tokenName12",
    "accessLevel": 50,
    "expiresAt": "2024-05-19T16:00:00+0000",
    "scopes": [
      "api"
    ],
    "state": "available",
    "taskState": "no task",
    "createdAt": "2024-05-17T03:05:28+0000",
    "updatedAt": "2024-05-17T03:05:28+0000"
  }
]

# 项目组受邀规则配置

管理项目组的受邀规则，工蜂会为新增项目匹配符合受邀规则的项目组，并将项目共享到目标项目组中。仅管理员可用。

# 创建项目组受邀规则

创建一个项目组受邀规则

POST  /api/v3/groups/:group_id/project_group_link_configs

参数：

参数	类型	描述
group_id	integer	项目组 ID 或者项目组全路径 namespace_full_path
source_type	String	规则来源类型，目前支持的类型为： `project_creator_org`(创建人所在组织架构)
source_id	Integer	来源类型 id
group_access_level	Integer	共享到该项目组时赋予的访问权限
group_access_expires_at	yyyy-MM-ddThh:mm:ssZ(可选)	共享到该项目组的过期时间，默认没有过期时间，如需指定需要大于当前时间，比如：2025-05-08T00:00:00+0000

返回值：

{
  "id": 59,
  "group_id": 344223,
  "config_type": "auto_create",
  "source_type": "project_creator_org",
  "source_id": 9,
  "created_by_id": 11266,
  "updated_by_id": 11266,
  "group_access_level": 30,
  "group_access_expires_at": "2024-06-23T09:13:00+0000",
  "created_at": "2024-06-04T06:43:39+0000",
  "updated_at": "2024-06-04T06:43:39+0000"
}

# 删除项目组受邀规则

删除一个项目组受邀规则

DELETE  /api/v3/groups/:group_id/project_group_link_configs/:id

参数：

参数	类型	描述
group_id	integer	项目组 ID 或者项目组全路径 namespace_full_path
id	integer	项目组受邀规则 id

返回值：

200或相关状态码

# 修改项目组受邀规则

修改一个项目组受邀规则

PUT  /api/v3/groups/:group_id/project_group_link_configs/:id

参数：

参数	类型	描述
group_id	integer	项目组 ID 或者项目组全路径 namespace_full_path
id	integer	项目组受邀规则 id
source_type	String(可选)	规则来源类型，目前支持的类型为： `project_creator_org`(创建人所在组织架构)
source_id	Integer(可选)	来源类型 id
group_access_level	Integer(可选)	共享到该项目组时赋予的访问权限
group_access_expires_at	yyyy-MM-ddThh:mm:ssZ(可选)	共享到该项目组的过期时间，默认没有过期时间，如需指定需要大于当前时间，比如：2025-05-08T00:00:00+0000

返回值：

200或相关状态码

# 查看项目组受邀规则

查看一个项目组受邀规则

GET  /api/v3/groups/:group_id/project_group_link_configs/:id

参数：

参数	类型	描述
group_id	integer	项目组 ID 或者项目组全路径 namespace_full_path
id	integer	项目组受邀规则 id

返回值：

{
  "id": 59,
  "group_id": 344223,
  "config_type": "auto_create",
  "source_type": "project_creator_org",
  "source_id": 10,
  "created_by_id": 11266,
  "updated_by_id": 11266,
  "group_access_level": 40,
  "group_access_expires_at": null,
  "created_at": "2024-06-04T06:43:40+0000",
  "updated_at": "2024-06-04T06:50:19+0000"
}

# 查看项目组受邀规则列表

查看项目组下所有项目组受邀规则

GET  /api/v3/groups/:group_id/project_group_link_configs

参数：

参数	类型	描述
group_id	integer	项目组 ID 或者项目组全路径 namespace_full_path

返回值：

[
  {
    "id": 39,
    "group_id": 344223,
    "config_type": "auto_create",
    "source_type": "project_creator_org",
    "source_id": 199,
    "created_by_id": 11266,
    "updated_by_id": 11266,
    "group_access_level": 40,
    "group_access_expires_at": "2023-09-14T07:17:37+0000",
    "created_at": "2024-05-23T09:13:00+0000",
    "updated_at": "2024-05-23T09:13:00+0000"
  },
  {
    "id": 58,
    "group_id": 344223,
    "config_type": "auto_create",
    "source_type": "project_creator_org",
    "source_id": 958,
    "created_by_id": 11266,
    "updated_by_id": 11266,
    "group_access_level": 30,
    "group_access_expires_at": "2024-09-14T07:17:37+0000",
    "created_at": "2024-05-23T11:11:38+0000",
    "updated_at": "2024-05-23T11:11:38+0000"
  }
]

# 项目组回调钩子

# 给项目组增加回调钩子

增加项目组回调钩子

POST /api/v3/groups/:id/hooks

参数：

参数	类型	描述
id	integer or string	项目组 ID 或项目组全路径 namespace_full_path
url	string	回调钩子地址
project_events	boolean (可选)	有项目事件触发回调钩子，如新建、删除、引用、解除引用、转移项目，默认 `true`
url_mask_variables	list (可选)	用于隐藏对外展示的 URL 例如：url_mask_variables: [{variable: "123456", mask:"token"} ] variable 需要隐藏的字符，mask 隐藏后对外显示的字符
token	string(可选)	用以校验收到的负载;此 token 不会在包含在返回值中

返回值：

{
  "id": 1,
  "url": "https://git.tencent.com/hook/push",
  "created_at": "2025-03-29T04:48:31+0000",
  "group_id": 2365,
  "project_events": true,
  "active": true
}

# 编辑项目组回调钩子

修改项目组中的回调钩子

PUT /api/v3/groups/:id/hooks/:hook_id

参数：

参数	类型	描述
id	integer or string	项目组 ID 或项目组全路径 namespace_full_path
url	string	回调钩子地址
project_events	boolean（可选）	有项目事件触发回调钩子，如新建、删除、引用、解除引用、转移项目，默认 `true`
token	string(可选)	用以校验收到的负载;此 token 不会在包含在返回值中

返回值：

{
  "id": 1,
  "url": "https://git.tencent.com/hook/push",
  "created_at": "2025-03-29T04:48:31+0000",
  "group_id": 2365,
  "project_events": false,
  "active": false
}

# 查询项目组单个回调钩子

根据回调钩子 id 查询项目组回调钩子

GET /api/v3/groups/:id/hooks/:hook_id

参数：

参数	类型	描述
id	integer or string	项目组 ID 或项目组全路径 namespace_full_path
hook_id	integer	回调钩子 id

返回值：

{
  "id": 2,
  "url": "https://git.tencent.com/hook/push",
  "created_at": "2025-03-29T04:48:31+0000",
  "group_id": 2,
  "project_events": true,
  "active": true
}

# 查询项目组回调钩子列表

在项目组中查询项目组回调钩子列表

GET /api/v3/groups/:id/hooks

参数：

参数	类型	描述
id	integer or string	项目组 ID 或项目组全路径 namespace_full_path
page	integer	分页（默认值：`1`）
per_page	integer	默认页面大小（默认值： `20`，最大值： `100`）

返回值：

[
  {
    "id": 1,
    "url": "https://git.tencent.com/hook/push",
    "created_at": "2025-03-29T04:48:31+0000",
    "group_id": 2,
    "project_events": false,
    "active": true
  }
]

# 删除项目组回调钩子

在项目组中删除某个指定的回调钩子

DELETE /api/v3/groups/:id/hooks/:hook_id

参数：

参数	类型	描述
id	integer or string	项目组 ID 或项目组全路径 namespace_full_path
hook_id	integer	回调钩子 id

返回值：

200 或相关状态码

# 回调钩子发送历史

# 查询项目组回调钩子发送历史列表

在项目组中查询某个指定的回调钩子发送历史列表

GET /api/v3/groups/:id/hooks/:hook_id/logs

参数：

参数	类型	描述
id	integer or string	项目组 ID 或项目组全路径 namespace_full_path
hook_id	integer	回调钩子 id
response_status	string（可选）	响应状态，可选`success`, `error`（默认全选）
created_after	yyyy-MM-dd'T'HH`:`mm`:`ssZ（可选）	返回给定时间及之后新增的发送历史；例如 2019-03-25T00:10:19+0000 或 2019-03-25T00:10:19+0800，时间参数必须转码，如“2019-03-25T00:10:19%2B0800”）
created_before	yyyy-MM-dd'T'HH`:`mm`:`ssZ（可选）	返回给定时间及之前新增的发送历史；例如 2019-03-25T00:10:19+0000 或 2019-03-25T00:10:19+0800，时间参数必须转码，如“2019-03-25T00:10:19%2B0800”）
order_by	integer（可选）	排序字段:`created_at`
sort	string（可选）	排序方式，允许`asc`,`desc`（默认`desc`）
page	integer（可选）	页数（默认值：1）
per_page	integer（可选）	默认页面大小（默认值：20，最大值：100）

返回值：

[
  {
    "id": 12031523,
    "web_hook_id": 1,
    "url": "http://www.xxx.com/",
    "trigger": "Project Hook",
    "request_headers": "{\"X-Event\":\"Project Hook\",\"X-Event-Type\":\"project\",\"X-Source-Type\":\"Group\",\"X-Source-ID\":\"1317426\",\"X-Gitlab-Event\":\"Project Hook\",\"X-Gitlab-Token\":null,\"X-Token\":null,\"X-TRACE-ID\":\"f2233b8bbfd44bda89e002a19be6cab0.93.17429605866280915\",\"X-Send-Timestamp\":\"1742960586631\",\"Content-Type\":\"application/json;charset=UTF-8\",\"Accept\":\"application/json\",\"User-Agent\":\"Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/44.0.2403.157 Safari/537.36\"}",
    "request_data": "{\"object_kind\":\"project\",\"operation_kind\":\"project_dereference\",\"user\":{\"name\":\"xxxx\",\"username\":\"xxxx\",\"avatar_url\":null,\"user_id\":1},\"group\":{\"group_id\":1317426,\"name\":\"hello\",\"path\":\"hello\",\"full_path\":\"hello\",\"homepage\":\"https://git.woa.com/groups/hello\"},\"object_attributes\":{\"project_id\":12486073,\"visibility_level\":10,\"project_visibility\":\"internal\",\"created_at\":\"2025-01-08T12:26:18+0000\",\"updated_at\":\"2025-01-08T12:26:18+0000\",\"name\":\"ha\",\"path\":\"ha\",\"path_with_namespace\":\"test/ha\"}}",
    "response_headers": "{\"Server\":\"WEBrick/1.4.2 (Ruby/2.6.3/2019-04-16)\",\"Date\":\"Wed, 26 Mar 2025 03:43:06 GMT\",\"Content-Length\":\"0\",\"Connection\":\"Keep-Alive\"}",
    "response_body": null,
    "response_status": "success",
    "execution_duration": 11,
    "internal_error_message": null,
    "created_at": "2025-03-26T03:43:07+0000",
    "updated_at": "2025-03-26T03:43:07+0000"
  }
]

# 查询项目组回调钩子中指定的发送历史

在项目组中查询某个回调钩子中指定的发送历史

GET /api/v3/groups/:id/hooks/:hook_id/logs/:hook_log_id

参数：

参数	类型	描述
id	integer or string	项目组 ID 或项目组全路径 namespace_full_path
hook_id	integer	回调钩子 id
hook_log_id	integer	回调钩子发送历史的 id

返回值：

{
  "id": 12031523,
  "web_hook_id": 1,
  "url": "http://www.xxx.com/",
  "trigger": "Project Hook",
  "request_headers": "{\"X-Event\":\"Project Hook\",\"X-Event-Type\":\"project\",\"X-Source-Type\":\"Group\",\"X-Source-ID\":\"1317426\",\"X-Gitlab-Event\":\"Project Hook\",\"X-Gitlab-Token\":null,\"X-Token\":null,\"X-TRACE-ID\":\"f2233b8bbfd44bda89e002a19be6cab0.93.17429605866280915\",\"X-Send-Timestamp\":\"1742960586631\",\"Content-Type\":\"application/json;charset=UTF-8\",\"Accept\":\"application/json\",\"User-Agent\":\"Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/44.0.2403.157 Safari/537.36\"}",
  "request_data": "{\"object_kind\":\"project\",\"operation_kind\":\"project_dereference\",\"user\":{\"name\":\"xxxx\",\"username\":\"xxxx\",\"avatar_url\":null,\"user_id\":1},\"group\":{\"group_id\":1317426,\"name\":\"hello\",\"path\":\"hello\",\"full_path\":\"hello\",\"homepage\":\"https://git.woa.com/groups/hello\"},\"object_attributes\":{\"project_id\":12486073,\"visibility_level\":10,\"project_visibility\":\"internal\",\"created_at\":\"2025-01-08T12:26:18+0000\",\"updated_at\":\"2025-01-08T12:26:18+0000\",\"name\":\"ha\",\"path\":\"ha\",\"path_with_namespace\":\"test/ha\"}}",
  "response_headers": "{\"Server\":\"WEBrick/1.4.2 (Ruby/2.6.3/2019-04-16)\",\"Date\":\"Wed, 26 Mar 2025 03:43:06 GMT\",\"Content-Length\":\"0\",\"Connection\":\"Keep-Alive\"}",
  "response_body": null,
  "response_status": "success",
  "execution_duration": 11,
  "internal_error_message": null,
  "created_at": "2025-03-26T03:43:07+0000",
  "updated_at": "2025-03-26T03:43:07+0000"
}

# 重放项目组回调钩子中指定的发送历史

在项目组中重放某个回调钩子中指定的发送历史

POST /api/v3/groups/:id/hooks/:hook_id/logs/:hook_log_id/retry

参数：

参数	类型	描述
id	integer or string	项目组 ID 或项目组全路径 namespace_full_path
hook_id	integer	回调钩子 id
hook_log_id	integer	回调钩子发送历史的 id

返回值：

200 或相关状态码

# 激活回调钩子

# 激活项目组回调钩子

在项目组中激活某个回调钩子

POST /api/v3/groups/:id/hooks/:hook_id/activate

参数：

参数	类型	描述
id	integer 或 string	项目组 ID 或项目组全路径 namespace_full_path
hook_id	integer	回调钩子 id

返回值：

true 或 false

项目组

← 访问控制命名空间 →