gitlab-automation

Rube MCP による GitLab の自動化

Composio の GitLab ツールキットを通じて、プロジェクト管理、課題追跡、マージリクエストのワークフロー、CI/CD パイプラインの監視、ブランチ管理、ユーザー管理などの GitLab 操作を自動化します。

ツールキットのドキュメント：composio.dev/toolkits/gitlab

前提条件

• Rube MCP が接続されていること（RUBE_SEARCH_TOOLS が利用可能）
• ツールキット gitlab を指定した RUBE_MANAGE_CONNECTIONS で、GitLab への接続が有効になっていること
• 必ず最初に RUBE_SEARCH_TOOLS を呼び出して、最新のツールスキーマを取得してください

セットアップ

Rube MCP を取得する：クライアントの設定で、https://rube.app/mcp を MCP サーバーとして追加します。API キーは不要です。エンドポイントを追加するだけで利用できます。

1. RUBE_SEARCH_TOOLS が応答することを確認し、Rube MCP が利用可能であることを確認します
2. ツールキット gitlab を指定して RUBE_MANAGE_CONNECTIONS を呼び出します
3. 接続が ACTIVE でない場合は、返された認証リンクに従って GitLab OAuth を完了します
4. ワークフローを実行する前に、接続ステータスが ACTIVE と表示されることを確認します

主なワークフロー

1. 課題を管理する

使用する場面：ユーザーが GitLab プロジェクトの課題の作成、更新、一覧表示、検索を希望する場合

ツールの呼び出し順序：

1. GITLAB_GET_PROJECTS - 対象プロジェクトを見つけ、ID を取得します［前提条件］
2. GITLAB_LIST_PROJECT_ISSUES - プロジェクトの課題を一覧表示し、絞り込みます［必須］
3. GITLAB_CREATE_PROJECT_ISSUE - 新しい課題を作成します［作成時に必須］
4. GITLAB_UPDATE_PROJECT_ISSUE - 既存の課題を更新します（タイトル、ラベル、状態、担当者）［更新時に必須］
5. GITLAB_LIST_PROJECT_USERS - 割り当てるユーザー ID を確認します［任意］

主なパラメーター：

• id：プロジェクト ID（整数）または URL エンコードされたパス（例："my-group/my-project"）
• title：課題のタイトル（作成時に必須）
• description：課題の本文（最大 1,048,576 文字）
• labels：カンマ区切りのラベル名（例："bug,critical"）
• add_labels / remove_labels：すべてを置き換えずにラベルを追加または削除します
• state："all"、"opened"、"closed" で絞り込みます
• state_event：課題の状態を変更する場合は "close" または "reopen" を指定します
• assignee_ids：ユーザー ID の配列。すべての割り当てを解除するには [0] を使用します
• issue_iid：プロジェクト内の内部課題 ID（更新時に必須）
• milestone：マイルストーンのタイトルで絞り込みます
• search：タイトルと説明を検索します
• scope："created_by_me"、"assigned_to_me"、または "all"
• page / per_page：ページネーション（per_page のデフォルト：20）

注意点：

• id には整数のプロジェクト ID または URL エンコードされたパスを指定できます。誤った ID を指定すると 4xx エラーが発生します
• issue_iid はプロジェクト内の ID（#42 のように表示）で、グローバルな課題 ID とは異なります
• labels フィールドのラベルは既存のラベルをすべて置き換えます。段階的に変更するには add_labels / remove_labels を使用してください
• assignee_ids に空の配列を設定しても割り当ては解除されません。代わりに [0] を使用してください
• updated_at フィールドを使用するには、管理者またはプロジェクト／グループのオーナー権限が必要です

2. マージリクエストの管理

使用する場面：ユーザーがプロジェクト内のマージリクエストの一覧表示、絞り込み、またはレビューを希望する場合

ツールの使用順序：

1. GITLAB_GET_PROJECT - プロジェクトの詳細を取得し、アクセスを確認します [前提条件]
2. GITLAB_GET_PROJECT_MERGE_REQUESTS - マージリクエストの一覧表示と絞り込みを行います [必須]
3. GITLAB_GET_REPOSITORY_BRANCHES - ソースブランチ／ターゲットブランチを確認します [任意]
4. GITLAB_LIST_ALL_PROJECT_MEMBERS - レビュアー／担当者を探します [任意]

主なパラメーター：

• id：プロジェクト ID、または URL エンコードされたパス
• state："opened"、"closed"、"locked"、"merged"、または "all"
• scope："created_by_me"（デフォルト）、"assigned_to_me"、または "all"
• source_branch / target_branch：ブランチ名で絞り込みます
• author_id / author_username：MR の作成者で絞り込みます
• assignee_id：担当者で絞り込みます（未割り当ての場合は None、割り当て済みの場合は Any を使用）
• reviewer_id / reviewer_username：レビュアーで絞り込みます
• labels：カンマ区切りのラベルで絞り込みます
• search：タイトルと説明を検索します
• wip：ドラフト MR の場合は "yes"、ドラフト以外の場合は "no"
• order_by："created_at"（デフォルト）、"title"、"merged_at"、"updated_at"
• view：最小限のフィールドを返す場合は "simple"
• iids[]：特定の MR 内部 ID で絞り込みます

注意点：

• デフォルトの scope は "created_by_me" で、結果が制限されます。すべてを一覧表示するには "all" を使用してください
• author_id と author_username は同時に指定できません
• reviewer_id と reviewer_username は同時に指定できません
• approved フィルターには mr_approved_filter 機能フラグが必要です（デフォルトでは無効）
• MR の履歴が多いと情報が煩雑になるため、フィルターと適度な per_page 値を使用してください

3. プロジェクトとリポジトリの管理

使用する場面：ユーザーがプロジェクトの一覧表示、新しいプロジェクトの作成、またはブランチの管理を希望する場合

ツールの使用順序：

1. GITLAB_GET_PROJECTS - フィルターを指定して、アクセス可能なすべてのプロジェクトを一覧表示します [必須]
2. GITLAB_GET_PROJECT - 特定のプロジェクトの詳細情報を取得します [任意]
3. GITLAB_LIST_USER_PROJECTS - 特定のユーザーが所有するプロジェクトを一覧表示します [任意]
4. GITLAB_CREATE_PROJECT - 新しいプロジェクトを作成します [作成時に必須]
5. GITLAB_GET_REPOSITORY_BRANCHES - プロジェクト内のブランチを一覧表示します [ブランチ操作時に必須]
6. GITLAB_CREATE_REPOSITORY_BRANCH - 新しいブランチを作成します [任意]
7. GITLAB_GET_REPOSITORY_BRANCH - 特定のブランチの詳細を取得します [任意]
8. GITLAB_LIST_REPOSITORY_COMMITS - コミット履歴を表示します [任意]
9. GITLAB_GET_PROJECT_LANGUAGES - 言語の内訳を取得します [任意]

主なパラメーター：

• name / path：プロジェクト名と URL で使用できるパス（作成時は両方必須）
• visibility："private"、"internal"、または "public"
• namespace_id：プロジェクトの配置先となるグループまたはユーザーの ID
• search：プロジェクトを大文字と小文字を区別せず、部分一致で検索します
• membership：ユーザーがメンバーであるプロジェクトに限定する場合は true
• owned：ユーザーが所有するプロジェクトに限定する場合は true
• project_id：ブランチ操作に使用するプロジェクト ID
• branch_name：新しいブランチの名前
• ref：新しいブランチ作成時のソースブランチまたはコミット SHA
• order_by："id"、"name"、"path"、"created_at"、"updated_at"、"star_count"、"last_activity_at"

注意点：

• すべてのプロジェクトを網羅するには GITLAB_GET_PROJECTS のページネーションが必要です。最初のページで停止すると、プロジェクトを見落とします
• 一部のレスポンスでは項目が data.details の下に格納されています。実際に返されたリスト構造を解析してください
• 後続の呼び出しのほとんどは正しい project_id に依存するため、まず GITLAB_GET_PROJECT で確認してください
• branch_name／ref／sha が無効だとクライアントエラーが発生します。まず GITLAB_GET_REPOSITORY_BRANCHES でブランチの存在を確認してください
• GITLAB_CREATE_PROJECT では name と path の両方が必須です

4. CI/CD パイプラインを監視する

使用する状況：ユーザーがパイプラインのステータスを確認したい場合、ジョブを一覧表示したい場合、または CI/CD の実行を監視したい場合

ツールの順序：

1. GITLAB_GET_PROJECT - プロジェクトへのアクセスを確認します［前提条件］
2. GITLAB_LIST_PROJECT_PIPELINES - フィルターを使ってパイプラインを一覧表示します［必須］
3. GITLAB_GET_SINGLE_PIPELINE - 特定のパイプラインの詳細情報を取得します［任意］
4. GITLAB_LIST_PIPELINE_JOBS - パイプライン内のジョブを一覧表示します［任意］

主なパラメーター：

• id：プロジェクト ID または URL エンコードされたパス
• status："created"、"waiting_for_resource"、"preparing"、"pending"、"running"、"success"、"failed"、"canceled"、"skipped"、"manual"、"scheduled" で絞り込みます
• scope："running"、"pending"、"finished"、"branches"、"tags"
• ref：ブランチ名またはタグ名
• sha：特定のコミット SHA
• source：パイプラインのソース（子パイプラインには "parent_pipeline" を使用します）
• order_by："id"（デフォルト）、"status"、"ref"、"updated_at"、"user_id"
• created_after / created_before：ISO 8601 形式の日付フィルター
• pipeline_id：ジョブを一覧表示するための特定のパイプライン ID
• include_retried：再試行されたジョブを含める場合は true（デフォルトは false）

注意点：

• パイプラインの履歴が多いと結果が煩雑になることがあります。status、ref、日付フィルターを使って結果を絞り込んでください
• 出力を扱いやすくするため、per_page には適度な値を使用してください
• パイプラインジョブの scope には、単一のステータス文字列またはステータスの配列を指定できます
• yaml_errors: true を指定すると、設定が無効なパイプラインのみが返されます

5. ユーザーとメンバーを管理する

使用する状況：ユーザーを検索したい場合、プロジェクトメンバーを一覧表示したい場合、またはユーザーのステータスを確認したい場合

ツールの順序：

1. GITLAB_GET_USERS - GitLab ユーザーを検索して一覧表示します［必須］
2. GITLAB_GET_USER - ID を指定して特定のユーザーの詳細を取得します［任意］
3. GITLAB_GET_USERS_ID_STATUS - ユーザーのステータスメッセージと在席状況を取得します［任意］
4. GITLAB_LIST_ALL_PROJECT_MEMBERS - すべてのプロジェクトメンバー（直接メンバーと継承メンバー）を一覧表示します［メンバー一覧の表示に必須］
5. GITLAB_LIST_PROJECT_USERS - 検索フィルターを使ってプロジェクトユーザーを一覧表示します［任意］

主なパラメーター：

• search：名前、ユーザー名、または公開メールアドレスで検索します
• username：ユーザー名を指定して特定のユーザーを取得します
• active / blocked：ユーザーの状態で絞り込みます
• id：メンバーを一覧表示するためのプロジェクト ID
• query：名前、メールアドレス、またはユーザー名でメンバーを絞り込みます
• state："awaiting" または "active" でメンバーを絞り込みます（Premium/Ultimate）
• user_ids：特定のユーザー ID で絞り込みます

注意点：

• 多くのユーザーフィルター（admins、auditors、extern_uid、two_factor）は管理者専用です
• GITLAB_LIST_ALL_PROJECT_MEMBERS には、直接メンバー、継承メンバー、招待されたメンバーが含まれます
• ユーザー検索では大文字と小文字は区別されませんが、メールアドレスのドメインの一部だけでは一致しない場合があります
• Premium/Ultimate の機能（state フィルター、シート情報）は無料プランでは利用できません

よくあるパターン

ID の解決

GitLab では、プロジェクトを識別するために次の 2 種類の形式を使用します：

• 数値 ID：整数のプロジェクト ID（例：123）
• URL エンコードされたパス：Namespace/project 形式（例："my-group%2Fmy-project" または "my-group/my-project"）
• Issue IID と ID：issue_iid はプロジェクト内の番号（#42）です。グローバルな id とは異なります
• ユーザー ID：数値です。search または username を指定して GITLAB_GET_USERS で解決します

ページネーション

GitLab では、オフセットベースのページネーションを使用します：

• page（1 から開始）と per_page（1～100、デフォルトは 20）を設定します
• レスポンスの項目数が per_page より少なくなるか、レスポンスが空になるまで、page を増やし続けます
• 合計件数はレスポンスヘッダー（X-Total、X-Total-Pages）で確認できる場合があります
• 正確な結果を得るため、最後までページネーションを行ってください

URL エンコードされたパス

プロジェクトのパスを識別子として使用する場合：

• スラッシュは URL エンコードする必要があります。my-group/my-project は my-group%2Fmy-project になります
• エンコードされていないパスを受け付けるツールもあります。各ツールのスキーマを確認してください
• 信頼性を高めるため、数値 ID が利用できる場合はそちらを優先してください

既知の注意点

ID 形式

• プロジェクトの id フィールドには、整数と文字列（URL エンコードされたパス）の両方を指定できます
• Issue の issue_iid はプロジェクト単位です。グローバルな Issue ID と混同しないでください
• パイプライン ID はプロジェクト単位の整数です
• ユーザー ID は、GitLab インスタンス全体で共通のグローバルな整数です

レート制限

• GitLab にはユーザーごとのレート制限があります（プランにより、通常は 1 分あたり 300～2000 リクエストです）
• 大量のパイプライン／Issue 履歴を取得する場合は、結果を絞り込むために日付とステータスのフィルターを使用してください
• 適切な per_page 値を指定し、節度を持ってページネーションを使用してください

パラメーターに関する注意点

• labels フィールドはすべてのラベルを置き換えます。段階的な変更には add_labels／remove_labels を使用してください
• assignee_ids: [0] はすべての割り当てを解除します。空の配列は何も変更しません
• scope のデフォルト値は異なります。MR では "created_by_me"、Issue では "all" です
• MR フィルターでは、author_id と author_username を同時に指定できません
• 日付パラメーターには ISO 8601 形式を使用します："2024-01-15T10:30:00Z"

プランによる制限

• 一部の機能には Premium／Ultimate が必要です：epic_id、weight、iteration_id、approved_by_ids、メンバーの state フィルター
• 管理者専用の機能：ユーザー管理フィルター、updated_at の上書き、カスタム属性
• mr_approved_filter 機能フラグはデフォルトで無効になっています

クイックリファレンス

タスク	ツールスラッグ	主なパラメーター
プロジェクトの一覧表示	GITLAB_GET_PROJECTS	search、membership、visibility
プロジェクトの詳細取得	GITLAB_GET_PROJECT	id
ユーザーのプロジェクト	GITLAB_LIST_USER_PROJECTS	id、search、owned
プロジェクトの作成	GITLAB_CREATE_PROJECT	name、path、visibility
Issue の一覧表示	GITLAB_LIST_PROJECT_ISSUES	id、state、labels、search
Issue の作成	GITLAB_CREATE_PROJECT_ISSUE	id、title、description、labels
Issue の更新	GITLAB_UPDATE_PROJECT_ISSUE	id、issue_iid、state_event
マージリクエストの一覧表示	GITLAB_GET_PROJECT_MERGE_REQUESTS	id、state、scope、labels
ブランチの一覧表示	GITLAB_GET_REPOSITORY_BRANCHES	project_id、search
ブランチの取得	GITLAB_GET_REPOSITORY_BRANCH	project_id、branch_name
ブランチの作成	GITLAB_CREATE_REPOSITORY_BRANCH	project_id、branch_name、ref
コミットの一覧表示	GITLAB_LIST_REPOSITORY_COMMITS	プロジェクト ID、ブランチ参照
プロジェクトの言語	GITLAB_GET_PROJECT_LANGUAGES	プロジェクト ID
パイプラインの一覧表示	GITLAB_LIST_PROJECT_PIPELINES	id、status、ref
パイプラインの取得	GITLAB_GET_SINGLE_PIPELINE	project_id、pipeline_id
パイプラインジョブの一覧表示	GITLAB_LIST_PIPELINE_JOBS	id、pipeline_id、scope
ユーザーの検索	GITLAB_GET_USERS	search、username、active
ユーザーの取得	GITLAB_GET_USER	ユーザー ID
ユーザーのステータス	GITLAB_GET_USERS_ID_STATUS	ユーザー ID
プロジェクトメンバーの一覧表示	GITLAB_LIST_ALL_PROJECT_MEMBERS	id、query、state
プロジェクトユーザーの一覧表示	GITLAB_LIST_PROJECT_USERS	id、search

---

Composio 提供