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