gitlab-group

组技能

使用 glab api 原始端点调用来执行 GitLab 组管理操作。

快速参考

操作	命令模式	风险
列出组	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 ...	⚠️

风险说明：- 安全 | ⚠️ 谨慎 | ⚠️⚠️ 警告 | ⚠️⚠️⚠️ 危险

何时使用此技能

始终在以下情况使用：

• 用户提到“组”“团队”“组织”或“命名空间”
• 用户想要管理组成员资格
• 用户询问子组或组项目
• 用户想要与另一个组共享项目

以下情况绝不要使用：

• 用户想要项目级设置（使用 gitlab-repo）
• 用户想要管理 CI/CD 组变量（使用带有 -g 标志的 gitlab-variable）

API 前提条件

必需的令牌范围： api

权限：

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

访问级别

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

可用命令

列出组

# 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

获取组详情

# Get by numeric ID
glab api groups/123 --method GET

# Get by path (URL-encode slashes)
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

创建组

# 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

可见性选项：

• private - 仅成员可见
• internal - 任何已认证用户
• public - 任何人可见

更新组

# 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

删除组

**警告：**这会永久删除该组及其所有项目！

# Delete group
glab api groups/123 --method DELETE

# With permanently_remove flag (immediate deletion)
glab api "groups/123?permanently_remove=true" --method DELETE

列出组成员

# 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

添加组成员

# Add as Developer
glab api groups/123/members --method POST \
  -f user_id=456 \
  -f access_level=30

# Add as Maintainer with expiration
glab api groups/123/members --method POST \
  -f user_id=456 \
  -f access_level=40 \
  -f expires_at="2025-12-31"

更新组成员

# 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"

移除组成员

# Remove member
glab api groups/123/members/456 --method DELETE

列出子组

# 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

列出组项目

# 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

与组共享项目

# Share project with group (Developer access)
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

常见工作流

工作流 1：创建团队结构

# 1. Create parent group
glab api groups --method POST \
  -f name="Engineering" \
  -f path="engineering" \
  -f visibility="internal"

# 2. Get parent group ID
parent_id=$(glab api "groups/$(echo 'engineering' | jq -Rr @uri)" | jq -r '.id')

# 3. Create subgroups
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

工作流 2：为团队成员办理入职

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

# 2. Add to group as Developer
glab api groups/123/members --method POST \
  -f user_id=$user_id \
  -f access_level=30

# 3. Verify membership
glab api groups/123/members/$user_id

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

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

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

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

# 2. Transfer to new group
glab api "projects/$project_id/transfer" --method PUT \
  -f namespace=456

故障排除

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

相关文档

• API 辅助工具
• 安全防护措施
• 快速参考
• GitLab Groups API