GitLab CLI Skill（MR/Issue）

基本準備

• 身份と認証の確認：
  • glab auth status で現在のインスタンスと "Logged in to <host> as <user>" の行を読み取ります。
  • ユーザー名を直接取得：GITLAB_HOST=<host> glab api /user | jq -r '.username'（ローカルに jq が必要。グローバルに GITLAB_HOST が設定済みの場合は glab api /user で可）。
  • 自作インスタンスは、環境変数 GITLAB_HOST で指定することを推奨します。単回のみ上書きしたい場合は、コマンドの前に GITLAB_HOST=<host> を追加するか、-R group/project を使用します。
• 出力フォーマットはデフォルトで十分なことが多いですが、機械可読性が必要な場合は --output json を使用します。
• MR または Issue の作成に成功すると、CLI から返される完全な URL がターミナルに単独の行で出力されます。

Issue のクイック表示

• 本文のみを表示：glab issue view <id|url>。
• コメント付き：glab issue view <id|url> --comments（必要に応じて --system-logs を追加）。
• リスト表示：glab issue list --state opened --per-page 50 [-R group/project]。ラベルでフィルタリングするには --label foo,bar を使用します。
• コメントの追加：glab issue note <id> -m "comment"。

MR のクイック表示

• MR の概要（必要に応じてフィールドを取得）：glab mr view <id|branch|url> --output json | jq -r '.title,.state,.author.username,.web_url,.description'。
• diff の表示：glab mr diff <id|branch> --color=never。生の patch が必要な場合は --raw を使用します。
• 関連 issue：glab mr issues <id>。

MR の作成（非インタラクティブ）

以下のタイトルと説明の仕様は、デフォルトの推奨フォーマットです。チーム/リポジトリ/プラットフォームなどの既存の制約と競合する場合は、既存の制約に従ってください。明確な要件（日本語が必要な場合など）がある場合は、そちらを優先します。カバーされていない部分は、この仕様に従って補完します。

1. ローカルブランチがプッシュ済みで、git status がクリーンであることを確認します。
2. タイトルのスタイル：英語、セマンティックコミットの仕様（例：feat(scope): short summary）に従い、簡潔で中心的な目的を記述します。タイトルに日本語が必要な場合でも、セマンティックプレフィックス（feat、fix など）は英語のままにする必要があります。
3. 説明のスタイル：英語、短い文章と箇条書きを使用し、コードを見ない読者にも動機と結果を理解できるようにすることを優先します。重要なのは、what/why/impact と必要な制約であり、詳細な経緯や開発プロセスの詳細は避けます。コンテキストが目標や制約を明確にするのに不十分な場合は、開発者に確認してから記述する必要があります。専門用語、関数名、メソッド名、クラス名、API 名、または設定キーを使用する場合は、可読性と正確性を向上させるために inline code（バッククォート）で囲みます。
4. 期待される本文の形式（簡潔でありながら情報が完全、必要に応じて無関係なブロックを削除）：

• ## Summary：1〜2つの短い文章で、機能レベルでの目的と影響を概説します。コードの変更を1つずつ説明するのではなく、機能の変更を強調します。層（Service/DAO など）をまたぎ、意味的に一貫性のある変更は、1つの機能記述にまとめる必要があります。
• ## Key changes：3〜5個の要点を箇条書きで示し、主要な変更点を記述します。
• ## Constraints / tradeoffs：制約、制限、または理想的でない選択肢がある場合は、簡単に説明します。
• ## Testing：検証方法、コマンド、またはシナリオ。テストされていない場合は、その理由を明記する必要があります。
• ## Notes（オプション）：レビューの注目点、リリースの注意事項、または今後の計画。

5. 特に強調：説明は、MR のマージ前後のシステムの変化と影響に焦点を当てる必要があり、開発中の途中経過や修正手順を記録することは避けてください。
6. heredoc を使用して複数行の説明を渡し、インタラクティブな編集を回避します。

   glab mr create \
   --title "feat(scope): short summary" \
   --description "$(cat <<'EOF'
   # 上記の形式で本文を埋めてください
   EOF
   )" \
   --target-branch main \
   --source-branch $(git branch --show-current) \
   --label bugfix \
   --draft \
   --yes

• 推奨パラメータ（必要に応じて有効化）：--remove-source-branch（マージ後にソースブランチを削除）、--squash-before-merge（マージ前に単一のコミットに圧縮）。チームの好みに応じて省略できます。
• その他の一般的なパラメータ：--reviewer user1,user2、--allow-collaboration。
• 既存の MR の変更：glab mr update <id> --title "..." --description "$(cat <<'EOF'\n...\nEOF\n)" --label ... --yes。

Issue の作成（非インタラクティブ）

• コマンドモードは MR と同様で、--title と heredoc で説明します。

  glab issue create \
  --title "feat: short summary" \
  --description "$(cat <<'EOF'\n- context\n- expected\nEOF\n)" \
  --label backlog,team-x \
  --assignee user1 \
  --yes

• プライベートにする必要がある場合：--confidential を追加します。締め切り --due-date YYYY-MM-DD。

共通オプションの早見表

• -R group/project：自作インスタンスのプロジェクトを指定します。完全な URL と同等です。
• --per-page と --page：リストまたはコメントをページ分割して表示する場合に使用します。

Issue/MR のタイトルまたは説明の更新（前提条件）

Issue または MR のタイトル/説明を更新する前に、現在のタイトル/本文（変更される内容）を読み取ってから変更する必要があります。