gitlab

GitLab スキル

概要

このスキルを使用すると、GitLab.com またはセルフマネージド GitLab インスタンス上のマージリクエスト、ノート、パイプライン、ジョブログを確認・更新できます。

このスキルは、GitLab のタスク向けにリポジトリ内で使用する Python ワークフローです。公式の GitLab MCP サーバー統合インターフェースではありません。

この最初の hve-core 実装は Python のみです。python scripts/gitlab.py で CLI を実行し、読み取り操作では出力を簡潔に保つために --fields を優先してください。

前提条件

このスキルには Python 3.11 以降が必要です。

コマンドを実行する前に、次の環境変数を設定してください。

変数	必須	例	用途
GITLAB_URL	はい	https://gitlab.com	GitLab インスタンスの URL
GITLAB_AUTH_MODE	任意	oauth	oauth または明示的な legacy-token 互換モード
GITLAB_OAUTH_CLIENT_ID	OAuth	Application ID	非機密 OAuth アプリケーション ID。クライアントシークレットは不要
GITLAB_TOKEN	レガシーモード	glpat-...	GITLAB_AUTH_MODE=legacy-token の場合にのみ受け付けられる PAT
GITLAB_PROFILE	いいえ	default	名前付き OAuth プロファイル
GITLAB_TOKEN_STORE	いいえ	path	OAuth ストアの上書き先。POSIX では親ディレクトリの所有者のみがアクセス可能である必要があります
GITLAB_ALLOW_INSECURE	いいえ	1	明示的に指定されたループバック HTTP 開発エンドポイントのみを許可
XDG_DATA_HOME	いいえ	path	デフォルトの OAuth ストアに使用する POSIX データルート
LOCALAPPDATA	いいえ	path	Windows 用に予約されたデータルート。OAuth の永続化は現在、Windows では安全のため失敗します
GITLAB_PROJECT	いいえ	group/project	プロジェクトのパスまたは数値のプロジェクト ID

GITLAB_PROJECT が設定されていない場合、スクリプトは git remote get-url origin からプロジェクトを検出しようとします。Git リポジトリ内にいない場合や、別のプロジェクトを対象にする場合は、変数を明示的に設定してください。

運用変数

変数	必須	用途
GITLAB_AUDIT_LOG	いいえ	JSON Lines 監査ログのパス。設定すると、すべてのリクエストが監査記録されます（監査ログを参照）。
GITLAB_AUDIT_ACTOR	いいえ	記録されるアクターの ID を上書きします（例：CI サービスプリンシパル）。
GITLAB_DEBUG	いいえ	失敗時に秘匿化されたトレースバックを出力するには 1 を設定します。秘匿化が無効になることはありません。

監査ログ

GITLAB_AUDIT_LOG が設定されている場合、スクリプトはすべての REST API リクエストと OAuth フォームリクエストについて、構造化された JSON Lines 形式の監査記録を書き込みます。監査はフェイルクローズかつ先行書き込み方式です。

• リクエストの送信前に attempt レコードを書き込みます。監査ログに書き込めない場合、操作は中止され、GitLab には何も送信されません。
• リクエストの完了後に outcome レコード（success または error。失敗時は HTTP ステータスを含む）を書き込みます。

REST レコードには、UTC タイムスタンプ、実行者、認証モード、正規化されたオリジン、 操作、HTTP メソッド、イベントが含まれます。OAuth レコードでは、実行者、オリジン、 クライアント、プロファイル、コード、本文、自由形式のエラーフィールドは含めず、 操作と失敗の種類を制限された値で記録します。リソースパス、クエリ、プロファイル名、 プロファイルの内容は除外されます。オプションの監査ログ出力先は、オリジンから テナントや内部ホストが特定される可能性があるため、運用上慎重に扱う必要があります。 アクセス制御されたパスに配置し、運用上必要な期間に限って保持してください。 トークンと認証ヘッダーは記録されません。リクエスト後に監査で失敗した場合は、 結果を変更せずに警告を出力します。

認証情報のローテーション

OAuth がデフォルトです。リダイレクト URI http://127.0.0.1:8766/callback と api スコープを設定し、非機密の ユーザー所有、グループ所有、またはセルフマネージドインスタンス所有のアプリケーションを 登録してください。GITLAB_URL と GITLAB_OAUTH_CLIENT_ID のみを設定し、 auth login または人の操作を伴う auth device-login を実行します。ブラウザーログインには、 ローテーションするリフレッシュトークンが必要です。アクセストークンは有効期限前に 更新され、置き換えはアトミックに保存されます。デバイスログインではアクセストークンのみの プロファイルが返される場合があり、その場合は有効期限後に再度デバイスログインが必要です。 プロバイダー側またはローカル側のクラッシュが発生するタイミングによっては、再ログインが 必要になることがあります。

デフォルトの保存先は POSIX では $XDG_DATA_HOME/hve-core/gitlab/gitlab-token.json で、 フォールバック先は ~/.local/share/hve-core/gitlab/gitlab-token.json です。 POSIX の保存ファイルとロックファイルは、専用の所有者のみがアクセスできるディレクトリ内で モード 0600 を使用します。Python 3.11 のモードビットでは所有者のみの DACL を強制できないため、 Windows では OAuth プロファイルの永続化はフェイルクローズになります。保護された OAuth バックエンドが 利用可能になるまでは、Windows では明示的に legacy-token モードを使用してください。

PAT 認証は GITLAB_AUTH_MODE=legacy-token で引き続き利用できます。 デバイス認証には、ブラウザーを利用できるデバイスでのユーザー承認が必要であり、 無人ワークロードの ID としては使用できません。

クイックスタート

環境変数をエクスポートしてから、--fields を指定して読み取りコマンドを実行します。

export GITLAB_URL="https://gitlab.com"
export GITLAB_OAUTH_CLIENT_ID="your-application-id"
export GITLAB_PROJECT="group/project"

python scripts/gitlab.py auth login
python scripts/gitlab.py mr-list opened --fields iid,title,author.name

既知のパイプラインのパイプラインジョブを読み取ります。

python scripts/gitlab.py pipeline-jobs 12345 --fields id,name,status,stage

パラメーターリファレンス

共通オプション

パラメーター	適用対象	例	説明
--fields	mr-list、mr-get、mr-notes、pipeline-get、pipeline-jobs	--fields iid,title,state	ドット記法で特定のフィールドを抽出し、簡潔な表形式またはキーと値の形式で出力します

コマンド

コマンド	引数	説明
auth login	なし	Authorization Code と PKCE で認証します
auth device-login	なし	人の支援を伴うデバイス認証を通じて認証します
auth status	なし	シークレットを含まないローカルプロファイルの状態を表示します
auth logout	なし	サーバーの認可を取り消さずに、ローカルプロファイルを 1 つ削除します
mr-list	[state] [max]	マージリクエストを一覧表示します。デフォルトではすべての状態を対象に 20 件表示します
mr-get	<mr-iid>	プロジェクト内の IID を指定して、1 件のマージリクエストを取得します
mr-create	<json> or stdin	JSON ペイロードからマージリクエストを作成します
mr-update	<mr-iid> <json> or stdin	JSON ペイロードからマージリクエストのフィールドを更新します
mr-comment	<mr-iid> <body> or stdin	マージリクエストにコメントを追加します
mr-notes	<mr-iid> [max]	マージリクエストのノートを一覧表示します。--fields を使用するとシステムノートは除外されます
pipeline-get	<pipeline-id>	数値 ID を指定して、1 件のパイプラインを取得します
pipeline-run	<branch-or-tag>	ブランチまたはタグのパイプラインを実行します
pipeline-jobs	<pipeline-id>	パイプラインのジョブを一覧表示します
job-log	<job-id>	ジョブのログ出力を未加工のまま表示します

スクリプトリファレンス

最近のオープンなマージリクエストを一覧表示します：

python scripts/gitlab.py mr-list opened --fields iid,title,author.name,user_notes_count

マージリクエストを 1 件取得します：

python scripts/gitlab.py mr-get 42 --fields iid,title,state,source_branch,target_branch

インライン JSON からマージリクエストを作成します：

python scripts/gitlab.py mr-create '{
  "source_branch": "feature/add-auth",
  "target_branch": "main",
  "title": "feat(auth): add OAuth login"
}'

標準入力からマージリクエストのコメントを追加します：

echo "CI passed. Ready for review." | python scripts/gitlab.py mr-comment 42

失敗したパイプラインを調査します：

python scripts/gitlab.py pipeline-get 12345 --fields id,status,web_url
python scripts/gitlab.py pipeline-jobs 12345 --fields id,name,status,stage
python scripts/gitlab.py job-log 67890

トラブルシューティング

症状	原因	解決方法
GITLAB_URL is not set	必須の環境変数が設定されていません	スクリプトを実行する前に GITLAB_URL をエクスポートします
GITLAB_TOKEN is not set for legacy-token mode	レガシーモードが明示されていますが、PAT がありません	GITLAB_AUTH_MODE=legacy-token の場合に限り、PAT をエクスポートします
GITLAB_TOKEN must not be set in oauth mode	レガシー PAT が OAuth 設定に混入しています	GITLAB_TOKEN を削除するか、legacy-token モードを明示的に選択します
OAuth persistence is unavailable on Windows	Windows プロファイルストア用の保護されたバックエンドがありません	legacy-token モードを明示的に使用するか、POSIX から OAuth を実行します
GITLAB_OAUTH_CLIENT_ID is not set	OAuth アプリケーションが設定されていません	パブリッククライアント ID を設定してから、auth login を実行します
Callback listener cannot bind	ポート 8766 が使用中か、転送されていません	ポートを解放するか、auth device-login を使用します
timed out waiting for the GitLab OAuth token store lock	別のプロセスがプロファイルストアのロックを保持しています	他のコマンドが終了するまで待ってから、再試行します
GitLab device response has invalid verification_uri	検証 URI が安全に表示できないか、GITLAB_URL と一致しません	GITLAB_URL がデバイス検証を提供するインスタンスと一致することを確認します
cannot parse git remote URL	プロジェクトの自動検出に失敗しました	GITLAB_PROJECT を明示的に設定します
HTTP 401 or HTTP 403	認証情報が無効か、アクセス権がありません	OAuth の場合は再ログインし、明示的なレガシーモードの場合は PAT をローテーションします
HTTP 404	プロジェクト、MR IID、パイプライン ID、またはジョブ ID が誤っています	GITLAB_PROJECT を確認し、数値の ID が正しいことを確認します
expected numeric ID	ID 引数に数値以外の値が渡されました	プロジェクトの MR IID と、数値のパイプライン ID またはジョブ ID を使用します
python3 is required or syntax errors on launch	サポートされていないインタープリターです	Python 3.11 以降でスクリプトを実行します

GitLab では、プロジェクト内の MR IID に !42 などを使用します。このスキルでは、 グローバルなマージリクエスト ID ではなく、数値の IID を指定します。