Group Skill

GitLab组操作技能

Group management operations for GitLab using

glab api

raw endpoint calls.

使用

glab api

原始端点调用进行GitLab组管理操作。

Quick Reference

快速参考

Operation	Command Pattern	Risk
List groups	`glab api groups`	-
Get group	`glab api groups/:id`	-
Create group	`glab api groups -X POST -f ...`	⚠️
Update group	`glab api groups/:id -X PUT -f ...`	⚠️
Delete group	`glab api groups/:id -X DELETE`	⚠️⚠️⚠️
List members	`glab api groups/:id/members`	-
Add member	`glab api groups/:id/members -X POST -f ...`	⚠️
Update member	`glab api groups/:id/members/:uid -X PUT -f ...`	⚠️
Remove member	`glab api groups/:id/members/:uid -X DELETE`	⚠️⚠️
List subgroups	`glab api groups/:id/subgroups`	-
List projects	`glab api groups/:id/projects`	-
Share with group	`glab api projects/:id/share -X POST -f ...`	⚠️

Risk Legend: - Safe | ⚠️ Caution | ⚠️⚠️ Warning | ⚠️⚠️⚠️ Danger

操作	命令格式	风险等级
列出组	`glab api groups`	-
获取组详情	`glab api groups/:id`	-
创建组	`glab api groups -X POST -f ...`	⚠️
更新组	`glab api groups/:id -X PUT -f ...`	⚠️
删除组	`glab api groups/:id -X DELETE`	⚠️⚠️⚠️
列出成员	`glab api groups/:id/members`	-
添加成员	`glab api groups/:id/members -X POST -f ...`	⚠️
更新成员	`glab api groups/:id/members/:uid -X PUT -f ...`	⚠️
移除成员	`glab api groups/:id/members/:uid -X DELETE`	⚠️⚠️
列出子组	`glab api groups/:id/subgroups`	-
列出组内项目	`glab api groups/:id/projects`	-
与组共享项目	`glab api projects/:id/share -X POST -f ...`	⚠️

风险等级说明: - 安全 | ⚠️ 注意 | ⚠️⚠️ 警告 | ⚠️⚠️⚠️ 危险

When to Use This Skill

何时使用此技能

ALWAYS use when:

User mentions "group", "team", "organization", "namespace"
User wants to manage group membership
User asks about subgroups or group projects
User wants to share a project with another group

NEVER use when:

User wants project-level settings (use gitlab-repo)
User wants to manage CI/CD group variables (use gitlab-variable with -g flag)

请务必在以下场景使用：

用户提及"组"、"团队"、"组织"、"命名空间"
用户需要管理组成员
用户询问子组或组内项目相关问题
用户需要与其他组共享项目

请勿在以下场景使用：

用户需要项目级设置（请使用gitlab-repo）
用户需要管理CI/CD组变量（请使用gitlab-variable并添加-g参数）

API Prerequisites

API前置要求

Required Token Scopes:

api

Permissions:

List/view groups: Any authenticated user (for visible groups)
Create groups: Depends on instance settings
Manage members: Owner or Maintainer role
Delete groups: Owner role

所需令牌权限:

api

权限说明:

列出/查看组：任何已认证用户（针对可见组）
创建组：取决于实例设置
管理成员：拥有Owner或Maintainer角色
删除组：拥有Owner角色

Access Levels

访问级别

Level	Value	Description
Guest	10	View issues and comments
Reporter	20	View code, create issues
Developer	30	Push code, create MRs
Maintainer	40	Manage project settings
Owner	50	Full control

级别	数值	描述
Guest	10	查看议题和评论
Reporter	20	查看代码、创建议题
Developer	30	推送代码、创建Merge Request
Maintainer	40	管理项目设置
Owner	50	完全控制权

Available Commands

可用命令

List Groups

列出组

bash

undefined

bash

undefined

List accessible groups

列出可访问的组

glab api groups --method GET

List with pagination

分页列出

glab api groups --paginate

Filter by search term

按搜索词过滤

glab api "groups?search=devops" --method GET

List only owned groups

仅列出自己拥有的组

glab api "groups?owned=true" --method GET

List top-level groups only

仅列出顶级组

glab api "groups?top_level_only=true" --method GET

undefined

glab api "groups?top_level_only=true" --method GET

undefined

Get Group Details

获取组详情

bash

undefined

bash

undefined

Get by numeric ID

通过数字ID获取

glab api groups/123 --method GET

Get by path (URL-encode slashes)

通过路径获取（对斜杠进行URL编码）

glab api "groups/$(echo 'my-group' | jq -Rr @uri)" --method GET

Get nested group

获取嵌套组

glab api "groups/$(echo 'parent/child' | jq -Rr @uri)" --method GET

Include additional details

包含额外详情

glab api "groups/123?with_projects=true" --method GET

undefined

glab api "groups/123?with_projects=true" --method GET

undefined

Create Group

创建组

bash

undefined

bash

undefined

Create top-level group

创建顶级组

glab api groups --method POST
-f name="My Team"
-f path="my-team"
-f visibility="private"

Create subgroup

创建子组

glab api groups --method POST
-f name="Backend Team"
-f path="backend"
-f parent_id=123
-f visibility="internal"

Create with description and features

创建带描述和功能的组

glab api groups --method POST
-f name="Dev Group"
-f path="dev-group"
-f description="Development team"
-f visibility="private"
-f request_access_enabled=true


**Visibility Options:**
- `private` - Only members can see
- `internal` - Any authenticated user
- `public` - Anyone can see

glab api groups --method POST
-f name="Dev Group"
-f path="dev-group"
-f description="Development team"
-f visibility="private"
-f request_access_enabled=true


**可见性选项**:
- `private` - 仅成员可见
- `internal` - 任何已认证用户可见
- `public` - 所有人可见

Update Group

更新组

bash

undefined

bash

undefined

Update name

更新名称

glab api groups/123 --method PUT
-f name="New Name"

Update visibility

更新可见性

glab api groups/123 --method PUT
-f visibility="internal"

Update multiple settings

更新多项设置

glab api groups/123 --method PUT
-f name="Updated Team"
-f description="New description"
-f request_access_enabled=false

undefined

glab api groups/123 --method PUT
-f name="Updated Team"
-f description="New description"
-f request_access_enabled=false

undefined

Delete Group

删除组

Warning: This permanently deletes the group and all its projects!

bash

undefined

警告: 此操作会永久删除组及其所有项目！

bash

undefined

Delete group

删除组

glab api groups/123 --method DELETE

With permanently_remove flag (immediate deletion)

使用permanently_remove参数（立即永久删除）

glab api "groups/123?permanently_remove=true" --method DELETE

undefined

glab api "groups/123?permanently_remove=true" --method DELETE

undefined

List Group Members

列出组成员

bash

undefined

bash

undefined

List all members

列出所有成员

glab api groups/123/members --method GET

Include inherited members

包含继承的成员

glab api groups/123/members/all --method GET

Search members

搜索成员

glab api "groups/123/members?query=john" --method GET

undefined

glab api "groups/123/members?query=john" --method GET

undefined

Add Group Member

添加组成员

bash

undefined

bash

undefined

Add as Developer

添加为Developer

glab api groups/123/members --method POST
-f user_id=456
-f access_level=30

Add as Maintainer with expiration

添加为Maintainer并设置过期时间

glab api groups/123/members --method POST
-f user_id=456
-f access_level=40
-f expires_at="2025-12-31"

undefined

glab api groups/123/members --method POST
-f user_id=456
-f access_level=40
-f expires_at="2025-12-31"

undefined

Update Group Member

更新组成员

bash

undefined

bash

undefined

Change access level

更改访问级别

glab api groups/123/members/456 --method PUT
-f access_level=40

Set expiration

设置过期时间

glab api groups/123/members/456 --method PUT
-f expires_at="2025-06-30"

undefined

glab api groups/123/members/456 --method PUT
-f expires_at="2025-06-30"

undefined

Remove Group Member

移除组成员

bash

undefined

bash

undefined

Remove member

移除成员

glab api groups/123/members/456 --method DELETE

undefined

glab api groups/123/members/456 --method DELETE

undefined

List Subgroups

列出子组

bash

undefined

bash

undefined

List immediate subgroups

列出直接子组

glab api groups/123/subgroups --method GET

List all descendant groups

列出所有子组

glab api groups/123/descendant_groups --method GET

With pagination

分页列出

glab api groups/123/subgroups --paginate

undefined

glab api groups/123/subgroups --paginate

undefined

List Group Projects

列出组内项目

bash

undefined

bash

undefined

List projects in group

列出组内项目

glab api groups/123/projects --method GET

Include subgroup projects

包含子组项目

glab api "groups/123/projects?include_subgroups=true" --method GET

Filter archived

过滤已归档项目

glab api "groups/123/projects?archived=false" --method GET

With pagination

分页列出

glab api groups/123/projects --paginate

undefined

glab api groups/123/projects --paginate

undefined

Share Project with Group

与组共享项目

bash

undefined

bash

undefined

Share project with group (Developer access)

与组共享项目（Developer权限）

glab api projects/789/share --method POST
-f group_id=123
-f group_access=30

Share with expiration

共享并设置过期时间

glab api projects/789/share --method POST
-f group_id=123
-f group_access=30
-f expires_at="2025-12-31"

Unshare

取消共享

glab api projects/789/share/123 --method DELETE

undefined

glab api projects/789/share/123 --method DELETE

undefined

Common Workflows

常见工作流

Workflow 1: Create Team Structure

工作流1：创建团队结构

bash

undefined

bash

undefined

1. Create parent group

1. 创建父组

glab api groups --method POST
-f name="Engineering"
-f path="engineering"
-f visibility="internal"

2. Get parent group ID

2. 获取父组ID

parent_id=$(glab api "groups/$(echo 'engineering' | jq -Rr @uri)" | jq -r '.id')

3. Create subgroups

3. 创建子组

glab api groups --method POST
-f name="Backend"
-f path="backend"
-f parent_id=$parent_id

glab api groups --method POST
-f name="Frontend"
-f path="frontend"
-f parent_id=$parent_id

undefined

glab api groups --method POST
-f name="Backend"
-f path="backend"
-f parent_id=$parent_id

glab api groups --method POST
-f name="Frontend"
-f path="frontend"
-f parent_id=$parent_id

undefined

Workflow 2: Onboard Team Member

工作流2：团队成员入职

bash

undefined

bash

undefined

1. Find user ID

1. 查找用户ID

user_id=$(glab api "users?search=john.doe" | jq -r '.[0].id')

2. Add to group as Developer

2. 添加到组并设置为Developer

glab api groups/123/members --method POST
-f user_id=$user_id
-f access_level=30

3. Verify membership

3. 验证成员身份

glab api groups/123/members/$user_id

undefined

glab api groups/123/members/$user_id

undefined

Workflow 3: Audit Group Access

工作流3：审计组访问权限

bash

undefined

bash

undefined

List all members including inherited

列出所有成员（包括继承的）

glab api groups/123/members/all --paginate |
jq -r '.[] | [.username, .access_level_description] | @tsv'

undefined

glab api groups/123/members/all --paginate |
jq -r '.[] | [.username, .access_level_description] | @tsv'

undefined

Workflow 4: Transfer Project Between Groups

工作流4：在组之间转移项目

bash

undefined

bash

undefined

1. Get project ID

1. 获取项目ID

project_id=$(glab api "projects/$(echo 'old-group/my-project' | jq -Rr @uri)" | jq -r '.id')

2. Transfer to new group

2. 转移到新组

glab api "projects/$project_id/transfer" --method PUT
-f namespace=456

undefined

glab api "projects/$project_id/transfer" --method PUT
-f namespace=456

undefined

Troubleshooting

故障排除

Issue	Cause	Solution
403 on create group	Group creation disabled	Check instance settings or contact admin
404 on group	Path not found	Verify group exists, check URL encoding
Cannot add member	User not found	Search users first with `glab api users?search=...`
Cannot delete group	Not owner	Need Owner role or admin access
Subgroup creation fails	Parent not found	Verify parent_id is correct

问题	原因	解决方案
创建组时返回403	组创建功能被禁用	检查实例设置或联系管理员
访问组时返回404	路径不存在	验证组是否存在，检查URL编码
无法添加成员	用户不存在	先使用 `glab api users?search=...` 搜索用户
无法删除组	不是Owner角色	需要Owner角色或管理员权限
子组创建失败	父组不存在	验证parent_id是否正确

gitlab-group

Original

Translation

Group Skill

GitLab组操作技能

Quick Reference

快速参考

When to Use This Skill

何时使用此技能

API Prerequisites

API前置要求

Access Levels

访问级别

Available Commands

可用命令

List Groups

列出组

List accessible groups

列出可访问的组

List with pagination

分页列出

Filter by search term

按搜索词过滤

List only owned groups

仅列出自己拥有的组

List top-level groups only

仅列出顶级组

Get Group Details

获取组详情

Get by numeric ID

通过数字ID获取

Get by path (URL-encode slashes)

通过路径获取（对斜杠进行URL编码）

Get nested group

获取嵌套组

Include additional details

包含额外详情

Create Group

创建组

Create top-level group

创建顶级组

Create subgroup

创建子组

Create with description and features

创建带描述和功能的组

Update Group

更新组

Update name

更新名称

Update visibility

更新可见性

Update multiple settings

更新多项设置

Delete Group

删除组

Delete group

删除组

With permanently_remove flag (immediate deletion)

使用permanently_remove参数（立即永久删除）

List Group Members

列出组成员

List all members

列出所有成员

Include inherited members

包含继承的成员

Search members

搜索成员

Add Group Member

添加组成员

Add as Developer

添加为Developer

Add as Maintainer with expiration

添加为Maintainer并设置过期时间

Update Group Member

更新组成员

Change access level

更改访问级别

Set expiration

设置过期时间

Remove Group Member