Back to Details

gitlab-group

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Group Skill

GitLab组操作技能

Group management operations for GitLab using 
glab api
raw endpoint calls.
使用
glab api
原始端点调用进行GitLab组管理操作。

Quick Reference

快速参考

OperationCommand PatternRisk
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

访问级别

LevelValueDescription
Guest10View issues and comments
Reporter20View code, create issues
Developer30Push code, create MRs
Maintainer40Manage project settings
Owner50Full control
级别数值描述
Guest10查看议题和评论
Reporter20查看代码、创建议题
Developer30推送代码、创建Merge Request
Maintainer40管理项目设置
Owner50完全控制权

Available Commands

可用命令

List Groups

列出组

bash
undefined
bash
undefined

List accessible groups

列出可访问的组

glab api groups --method GET
glab api groups --method GET

List with pagination

分页列出

glab api groups --paginate
glab api groups --paginate

Filter by search term

按搜索词过滤

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

List only owned groups

仅列出自己拥有的组

glab api "groups?owned=true" --method GET
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
glab api groups/123 --method GET

Get by path (URL-encode slashes)

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

glab api "groups/$(echo 'my-group' | jq -Rr @uri)" --method GET
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
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"
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"
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"
glab api groups/123 --method PUT
-f name="New Name"

Update visibility

更新可见性

glab api groups/123 --method PUT
-f visibility="internal"
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
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
glab api groups/123/members --method GET

Include inherited members

包含继承的成员

glab api groups/123/members/all --method GET
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
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
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
glab api groups/123/subgroups --method GET

List all descendant groups

列出所有子组

glab api groups/123/descendant_groups --method GET
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
glab api groups/123/projects --method GET

Include subgroup projects

包含子组项目

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

Filter archived

过滤已归档项目

glab api "groups/123/projects?archived=false" --method GET
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
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"
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"
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')
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')
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
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')
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

故障排除

IssueCauseSolution
403 on create groupGroup creation disabledCheck instance settings or contact admin
404 on groupPath not foundVerify group exists, check URL encoding
Cannot add memberUser not foundSearch users first with 
glab api users?search=...
Cannot delete groupNot ownerNeed Owner role or admin access
Subgroup creation failsParent not foundVerify parent_id is correct
问题原因解决方案
创建组时返回403组创建功能被禁用检查实例设置或联系管理员
访问组时返回404路径不存在验证组是否存在，检查URL编码
无法添加成员用户不存在先使用
glab api users?search=...
搜索用户
无法删除组不是Owner角色需要Owner角色或管理员权限
子组创建失败父组不存在验证parent_id是否正确

Related Documentation

相关文档