Who can create or delete groups?

Create and delete group operations require Owner or Maintainer level permissions on the target group or instance, per GitLab permissions.

How do visibility settings affect group access?

Visibility options control who can see the group: private (members only), internal (any authenticated user), or public (anyone).

gitlab-group

npx machina-cli add skill grandcamel/GitLab-Assistant-Skills/gitlab-group --openclaw

Files (1)

SKILL.md

8.0 KB

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

Overview

This skill enables managing GitLab groups through the glab API. It covers listing and viewing groups, creating, updating, and deleting groups, managing group members, listing subgroups and group projects, and sharing projects with groups.

How This Skill Works

The skill uses glab api calls to interact with GitLab REST endpoints for groups and related resources. Operations map to HTTP methods (GET for read, POST for create, PUT for update, DELETE for delete) and are demonstrated via concrete command patterns in the Quick Reference.

When to Use It

You need to list or view groups you have access to, including filtering by search, ownership, or top level.
You want to create a new group or sub-group with specific visibility and metadata.
You need to update or delete an existing group, or modify its details.
You must manage group membership (add, update, or remove members).
You want to list subgroups or group projects, or share a project with a group.

Quick Start

Step 1: Install and authenticate with glab, ensuring the API scope is granted in your token.
Step 2: Choose an operation (list, get, create, update, delete, manage members, share) and run the corresponding glab api command from the Quick Reference.
Step 3: Review the response, handle any errors, and adjust permissions or visibility as needed.

Best Practices

Ensure you have the correct permissions (Owner or Maintainer) before creating, updating, or deleting groups.
Specify clear visibility and descriptive metadata when creating groups (private/internal/public).
URL-encode group paths and handle nested groups properly when constructing endpoints.
Use pagination when listing groups or members to avoid missing results in large instances.
Validate API responses and handle errors gracefully to avoid partial changes.

Example Use Cases

List groups you can view: glab api groups --method GET
Get details for a specific group: glab api groups/123 --method GET
Create a private top-level group: glab api groups --method POST -f name="DevOps" -f path="devops" -f visibility="private"
Add a member to a group: glab api groups/123/members -X POST -f user_id=45 -f access_level=40
Share a project with a group: glab api projects/987/share -X POST -f group_id=123

Frequently Asked Questions

Add this skill to your agents

gitlab-group

Group Skill

Quick Reference

When to Use This Skill

API Prerequisites

Access Levels

Available Commands

List Groups

Get Group Details

Create Group

Update Group

Delete Group

List Group Members

Add Group Member

Update Group Member

Remove Group Member

List Subgroups

List Group Projects

Share Project with Group

Common Workflows

Workflow 1: Create Team Structure

Workflow 2: Onboard Team Member

Workflow 3: Audit Group Access

Workflow 4: Transfer Project Between Groups

Troubleshooting

Related Documentation

Source

Overview

How This Skill Works

When to Use It

Quick Start

Best Practices

Example Use Cases

Frequently Asked Questions

gitlab-group

Group Skill

Quick Reference

When to Use This Skill

API Prerequisites

Access Levels

Available Commands

List Groups

Get Group Details

Create Group

Update Group

Delete Group

List Group Members

Add Group Member

Update Group Member

Remove Group Member

List Subgroups

List Group Projects

Share Project with Group

Common Workflows

Workflow 1: Create Team Structure

Workflow 2: Onboard Team Member

Workflow 3: Audit Group Access

Workflow 4: Transfer Project Between Groups

Troubleshooting

Related Documentation

Source

Overview

How This Skill Works

When to Use It

Quick Start

Best Practices

Example Use Cases

Frequently Asked Questions

What token scope is required to use this skill?

Who can create or delete groups?

How do visibility settings affect group access?