GitLab CLI (glab) スキル

ターミナルから GitLab 操作を実行するための公式 GitLab CLI である glab の使用ガイダンスを提供します。

このスキルを使用する場合

ユーザーが以下を必要とする場合に使用してください:

• マージリクエストの作成、レビュー、または管理
• GitLab イシューの操作
• CI/CD パイプラインの監視またはトリガー
• リポジトリのクローンまたは管理
• コマンドラインから GitLab 操作を実行

前提条件

コマンドを実行する前に glab のインストール確認:

glab --version

インストールされていない場合は、ユーザーに通知し、プラットフォーム固有のインストールガイダンスを提供してください。

認証クイックスタート

ほとんどの glab 操作には認証が必要です:

# インタラクティブ認証
glab auth login

# 認証ステータスの確認
glab auth status

# セルフホストの GitLab の場合
glab auth login --hostname gitlab.example.org

# 環境変数を使用
export GITLAB_TOKEN=your-token
export GITLAB_HOST=gitlab.example.org  # セルフホストの場合

コアワークフロー

マージリクエストの作成

# 1. ブランチがプッシュされていることを確認
git push -u origin feature-branch

# 2. MR を作成
glab mr create --title "Add feature" --description "Implements X"

# レビュアーとラベルを指定
glab mr create --title "Fix bug" --reviewer=alice,bob --label="bug,urgent"

マージリクエストのレビュー

# 1. あなたのレビューを待つ MR をリスト
glab mr list --reviewer=@me

# 2. MR をローカルにチェックアウトしてテスト
glab mr checkout <mr-number>

# 3. テスト後、承認
glab mr approve <mr-number>

# 4. 一般的なコメントを追加
glab mr note <mr-number> -m "Please update tests"

インラインDiffNoteコメントの投稿

diff の特定の行にコメントを固定するには (つまり DiffNote)、Content-Type: application/json ヘッダー付きで JSON 本文を使用する必要があります。-F フォームフィールドを使用すると、固定されていない DiscussionNote が作成されます。

# MR から SHA 値を取得
glab mr view <id> --output=json | grep -oP '"(base_sha|head_sha|start_sha)":\s*"\K[0-9a-f]{40}'

# 新しい行に DiffNote を投稿
glab api --method POST "projects/:id/merge_requests/:iid/discussions" \
  -H "Content-Type: application/json" \
  --input - <<'JSONEOF'
{
  "body": "Your review comment here",
  "position": {
    "base_sha": "<base_sha>",
    "start_sha": "<start_sha>",
    "head_sha": "<head_sha>",
    "position_type": "text",
    "new_path": "path/to/file.js",
    "new_line": 42
  }
}
JSONEOF

DiffNote の主要なルール:

• 常に --input - をヒアドキュメントで使用し、-H "Content-Type: application/json" を指定してください。position オブジェクトに -F を決して使用しないでください — サイレントに DiscussionNote が作成されます。
• 行番号は新しいファイルの行番号であり、diff ハンクヘッダー (@@ -old,count +new,count @@) から計算されます。diff 出力の行番号ではなく、ハンク開始からコンテキスト行と + 行のみをカウントしてください。
• 現在のワーキングブランチではなく、MR ソースブランチで検出を確認してください (git fetch origin <branch> その後 git grep)。
• 既存のノートを更新するには: glab api --method PUT "projects/:id/merge_requests/:iid/notes/:note_id" -H "Content-Type: application/json" --input - <<< '{"body":"updated text"}'
• GitLab には GitHub のようなバッチ「レビュー送信」API がありません。DiffNote を個別に投稿してください。
• discussion または note ID を見つけるには: glab api "projects/:id/merge_requests/:iid/discussions" --paginate

イシューの管理

# ラベル付きでイシューを作成
glab issue create --title "Bug in login" --label=bug

# MR をイシューにリンク
glab mr create --title "Fix login" --description "Closes #<issue-number>"

# あなたに割り当てられたイシューをリスト
glab issue list --assignee=@me

CI/CD の監視

# 進行中のパイプラインを監視
glab pipeline ci view

# パイプラインステータスをチェック
glab ci status

# 失敗した場合、ログを表示
glab ci trace

# 失敗したパイプラインを再試行
glab ci retry

# プッシュする前に CI config をリント
glab ci lint

一般的なパターン

リポジトリコンテキスト外での作業

Git リポジトリにいない場合は、リポジトリを指定してください:

glab mr list -R owner/repo
glab issue list -R owner/repo

セルフホストの GitLab

すべてのコマンドにホスト名を設定:

export GITLAB_HOST=gitlab.example.org
# またはコマンドごと
glab repo clone gitlab.example.org/owner/repo

未解決の MR コメントのリスト

glab api "projects/:id/merge_requests/{mr}/discussions?per_page=100" | jq '[.[] | select(.notes[0].resolvable == true and .notes[0].resolved == false) | {id: .notes[0].id, body: .notes[0].body[0:100], path: .notes[0].position.new_path, line: .notes[0].position.new_line}]'

自動化とスクリプティング

パースのために JSON 出力を使用:

glab mr list --output=json | jq '.[] | .title'

MR ノート/スレッドへの返信

glab mr note はスタンドアロンコメントを作成します。discussion スレッド内で返信するには、API を使用してください:

# 1. ノートを含む discussion_id を見つけます
glab api "projects/:id/merge_requests/{mr}/discussions" | jq '.[] | select(.notes[].id == {note_id}) | .id'

# 2. discussion スレッドに返信を投稿
glab api --method POST "projects/:id/merge_requests/{mr}/discussions/{discussion_id}/notes" --field body="Your reply"

例:

# ノート 13698970 の discussion_id を取得
glab api "projects/:id/merge_requests/1013/discussions" | jq '.[] | select(.notes[].id == 13698970) | {id}'
# 戻り値: {"id": "5356c3552e72e7b4c49276eb4dacfe3efe5c2c5c"}

# そのスレッドに返信
glab api --method POST "projects/:id/merge_requests/1013/discussions/5356c3552e72e7b4c49276eb4dacfe3efe5c2c5c/notes" --field body="Thanks for the review!"

API コマンドの使用

glab api コマンドは GitLab API への直接アクセスを提供します:

# 基本的な API 呼び出し
glab api projects/:id/merge_requests

# 重要: ページネーションはフラグではなく URL クエリパラメーターを使用します
# ❌ 間違い: glab api --per-page=100 projects/:id/jobs
# ✓ 正しい: glab api "projects/:id/jobs?per_page=100"

# すべてのページを自動フェッチ
glab api --paginate "projects/:id/pipelines/123/jobs?per_page=100"

# データを含む POST
glab api --method POST projects/:id/issues --field title="Bug" --field description="Details"

ベストプラクティス

1. 認証を確認 コマンド実行前: glab auth status
2. --help を使用 コマンドオプションを調べるには: glab <command> --help
3. MR をイシューにリンク MR の説明で "Closes #123" を使用
4. プッシュ前に CI config をリント: glab ci lint
5. コマンドが失敗した場合、リポジトリコンテキストをチェック: git remote -v

一般的なコマンド クイックリファレンス

マージリクエスト:

• glab mr list --assignee=@me - あなたに割り当てられた MR
• glab mr list --reviewer=@me - あなたがレビューする MR
• glab mr create - 新しい MR を作成
• glab mr checkout <number> - MR をローカルでテスト
• glab mr approve <number> - MR を承認
• glab mr merge <number> - 承認された MR をマージ

イシュー:

• glab issue list - すべてのイシューをリスト
• glab issue create - 新しいイシューを作成
• glab issue close <number> - イシューをクローズ

CI/CD:

• glab pipeline ci view - パイプラインを監視
• glab ci status - ステータスをチェック
• glab ci lint - .gitlab-ci.yml を検証
• glab ci retry - 失敗したパイプラインを再試行

リポジトリ:

• glab repo clone owner/repo - リポジトリをクローン
• glab repo view - リポジトリの詳細を表示
• glab repo fork - リポジトリをフォーク

段階的な情報開示

詳細なコマンドドキュメントについては、以下を参照:

• references/commands-detailed.md - すべてのフラグとオプション付きの包括的なコマンドリファレンス
• references/quick-reference.md - 圧縮されたコマンドチートシート
• references/troubleshooting.md - 詳細なエラーシナリオと解決策

以下の場合にこれらのリファレンスをロード:

• ユーザーが特定のフラグまたはオプションの詳細を必要とする
• 認証または接続の問題をトラブルシューティング
• 高度な機能 (API、スケジュール、変数など) を操作

一般的な問題クイックフィックス

"command not found: glab" - glab をインストールするか PATH を確認

"401 Unauthorized" - glab auth login を実行

"404 Project Not Found" - リポジトリ名とアクセス権限を確認

"not a git repository" - リポジトリに移動するか -R owner/repo フラグを使用

"source branch already has a merge request" - glab mr list を使用して既存の MR を見つける

詳細なトラブルシューティングについては、references/troubleshooting.md をロード。

注記

• glab は Git リモートからリポジトリコンテキストを自動検出
• ほとんどのコマンドには --web フラグがありブラウザで開く
• スクリプティングと自動化には --output=json を使用
• 複数の GitLab アカウントを同時に認証可能
• コマンドは Git 設定と現在のリポジトリコンテキストを尊重