glab

GitLab CLI (glab) スキル

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

このスキルを使用するタイミング

次の操作が必要な場合に呼び出します。

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

前提条件

コマンドを実行する前に、glab がインストールされていることを確認します。

glab --version

インストールされていない場合は、ユーザーに伝え、プラットフォームに応じたインストール手順を案内します。

認証クイックスタート

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

# Interactive authentication
glab auth login

# Check authentication status
glab auth status

# For self-hosted GitLab
glab auth login --hostname gitlab.example.org

# Using environment variables
export GITLAB_TOKEN=your-token
export GITLAB_HOST=gitlab.example.org  # for self-hosted

主なワークフロー

マージリクエストの作成

# 1. Ensure branch is pushed
git push -u origin feature-branch

# 2. Create MR
glab mr create --title "Add feature" --description "Implements X"

# With reviewers and labels
glab mr create --title "Fix bug" --reviewer=alice,bob --label="bug,urgent"

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

# 1. List MRs awaiting your review
glab mr list --reviewer=@me

# 2. Checkout MR locally to test
glab mr checkout <mr-number>

# 3. After testing, approve
glab mr approve <mr-number>

# 4. Add a general comment
glab mr note <mr-number> -m "Please update tests"

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

コメントを差分内の特定の行に紐付ける（DiffNote）には、Content-Type: application/json ヘッダーを付けた JSON ボディを必ず使用する必要があります。-F フォームフィールドを使用すると、紐付けのない DiscussionNote が作成されます。

# Get SHA values from the MR
glab mr view <id> --output=json | grep -oP '"(base_sha|head_sha|start_sha)":\s*"\K[0-9a-f]{40}'

# Post a DiffNote on a new line
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 の主なルール：

• heredoc と -H "Content-Type: application/json" を付けて、必ず --input - を使用します。position オブジェクトに -F を使用しないでください。代わりに DiscussionNote が作成されますが、そのことは通知されません。
• 行番号は差分の出力行番号ではなく、差分ハンクのヘッダー（@@ -old,count +new,count @@）から算出する新しいファイルの行番号です。ハンクの開始位置からコンテキスト行と + 行だけを数えます。
• 現在の作業ブランチではなく、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 のような一括の「Submit Review」API はありません。DiffNote は個別に投稿してください。
• ディスカッションまたはノートの ID を確認するには、次を使用します：glab api "projects/:id/merge_requests/:iid/discussions" --paginate

イシューの管理

# Create issue with labels
glab issue create --title "Bug in login" --label=bug

# Link MR to issue
glab mr create --title "Fix login" --description "Closes #<issue-number>"

# List your assigned issues
glab issue list --assignee=@me

CI/CD の監視

# Watch pipeline in progress
glab pipeline ci view

# Check pipeline status
glab ci status

# View logs if failed
glab ci trace

# Retry failed pipeline
glab ci retry

# Lint CI config before pushing
glab ci lint

よくあるパターン

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

Git リポジトリ内にいない場合は、リポジトリを指定します。

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

セルフホストの GitLab

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

export GITLAB_HOST=gitlab.example.org
# or per-command
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 は単独のコメントを作成します。ディスカッションスレッド内で返信するには、API を使用します。

# 1. Find the discussion_id containing the note
glab api "projects/:id/merge_requests/{mr}/discussions" | jq '.[] | select(.notes[].id == {note_id}) | .id'

# 2. Post reply to the discussion thread
glab api --method POST "projects/:id/merge_requests/{mr}/discussions/{discussion_id}/notes" --field body="Your reply"

例：

# Get discussion_id for note 13698970
glab api "projects/:id/merge_requests/1013/discussions" | jq '.[] | select(.notes[].id == 13698970) | {id}'
# Returns: {"id": "5356c3552e72e7b4c49276eb4dacfe3efe5c2c5c"}

# Reply to that thread
glab api --method POST "projects/:id/merge_requests/1013/discussions/5356c3552e72e7b4c49276eb4dacfe3efe5c2c5c/notes" --field body="Thanks for the review!"

API コマンドの使用

glab api コマンドを使用すると、GitLab API に直接アクセスできます。

# Basic API call
glab api projects/:id/merge_requests

# IMPORTANT: Pagination uses query parameters in URL, NOT flags
# ❌ WRONG: glab api --per-page=100 projects/:id/jobs
# ✓ CORRECT: glab api "projects/:id/jobs?per_page=100"

# Auto-fetch all pages
glab api --paginate "projects/:id/pipelines/123/jobs?per_page=100"

# POST with data
glab api --method POST projects/:id/issues --field title="Bug" --field description="Details"

ベストプラクティス

1. コマンドを実行する前に認証を確認します：glab auth status
2. --help を使用してコマンドのオプションを確認します：glab <command> --help
3. MR の説明に「Closes #123」と記載して、MR をイシューにリンクします
4. プッシュする前にCI 設定を lint します：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 の設定と現在のリポジトリのコンテキストを反映します