gitlab-group

name	gitlab-group
description	GitLab group operations via API. ALWAYS use this skill when user wants to: (1) list/view groups, (2) create/update/delete groups, (3) manage group members, (4) list subgroups or group projects, (5) share projects with groups.
version	1.0.0
author	GitLab-Assistant-Skills
license	MIT
allowed-tools	["Bash","Read","Glob","Grep"]

Group Skill

Group management operations for GitLab using glab api raw endpoint calls.

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

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)

API Prerequisites

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

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

Available Commands

List Groups

# 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 Group Details

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

# 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

Update Group

# 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

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

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

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

List Group Members

# 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 Group Member

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

Update Group Member

# 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 Group Member

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

List Subgroups

# 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 Group Projects

# 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

# 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

Common Workflows

Workflow 1: Create Team Structure

# 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

Workflow 2: Onboard Team Member

# 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

Workflow 3: Audit Group Access

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

Workflow 4: Transfer Project Between Groups

# 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

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

Related Documentation

• API Helpers
• Safeguards
• Quick Reference
• GitLab Groups API