gitlab-group

# 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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! ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # Remove member glab api groups/123/members/456 --method DELETE ``` ### List Subgroups ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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](../shared/docs/API_HELPERS.md) - [Safeguards](../shared/docs/SAFEGUARDS.md) - [Quick Reference](../shared/docs/QUICK_REFERENCE.md) - [GitLab Groups API](https://docs.gitlab.com/ee/api/groups.html)