attach-review-to-pr

プルリクエストに行を指定したレビューコメントを追加する方法

このガイドでは、GitHub CLI（gh）API、または利用できない場合は mcp__github_inline_comment__create_inline_comment を使用して、GitHub UI で特定のコード行にコメントできるのと同様に、プルリクエストに行を指定したレビューコメントを追加する方法を説明します。

推奨される方法：MCP GitHub ツールを使用する

利用可能な場合は、プルリクエストに行を指定したインラインコメントを投稿するために、mcp__github_inline_comment__create_inline_comment MCP ツールを使用してください。この方法は GitHub の UI との連携に優れており、推奨される方法です。

代替方法：MCP ツールを利用できない場合は、以下で説明する GitHub CLI（gh）API メソッドを使用してください。

• 単一のコメントの場合：/comments エンドポイントを使用します（行を指定した単一のコメントを追加するを参照）
• 複数のコメントの場合：/reviews エンドポイントを使用します（行を指定した複数のコメントをまとめて追加するを参照）

概要

gh pr review は基本的なレビュー機能（承認、変更の要求、一般的なコメント）を提供しますが、行を指定したコメントには直接対応していません。特定のコード行にコメントを追加するには、低レベルの gh api コマンドを使用して、GitHub の REST API を直接呼び出す必要があります。

前提条件

1. GitHub CLI がインストールされ、認証済みであること：

   gh auth status
   

2. レビュー対象のリポジトリとプルリクエストへのアクセス権があること

GitHub のレビューコメントシステムについて

GitHub の PR コメントには 2 種類あります。

1. Issue コメント - PR の会話に対する一般的なコメント
2. レビューコメント - コードの変更箇所に対する、行を指定したコメント

レビューコメントは、次の 2 つの方法で追加できます。

• 単一のコメント - /pulls/{pr}/comments エンドポイントを使用
• 複数のコメントを含むレビュー - /pulls/{pr}/reviews エンドポイントを使用

行を指定した単一のコメントを追加する

基本構文

gh api repos/{owner}/{repo}/pulls/{pr_number}/comments \
  -f body='Your comment text here' \
  -f commit_id='<commit-sha>' \
  -f path='path/to/file.js' \
  -F line=42 \
  -f side='RIGHT'

パラメーターの説明

パラメーター	型	必須	説明
body	string	はい	レビューコメントのテキスト（Markdown に対応）
commit_id	string	はい	コメント対象のコミットの SHA
path	string	はい	コメント対象ファイルへの相対パス
line	integer	はい	diff 内の行番号（整数には -F を使用）
side	string	はい	新規または変更された行には RIGHT、削除された行には LEFT
start_line	integer	いいえ	複数行コメントの開始行
start_side	string	いいえ	複数行コメントの開始側

パラメーターフラグ

• -f（--field）- 文字列値に使用します
• -F（--field）- 整数値に使用します（大文字の F に注意してください）

完全な例

# First, get the latest commit SHA for the PR
gh api repos/NeoLabHQ/learning-platform-app/pulls/4 --jq '.head.sha'

# Then add your comment
gh api repos/NeoLabHQ/learning-platform-app/pulls/4/comments \
  -f body='Consider adding error handling here. Should we confirm the lesson was successfully marked as completed before navigating away?' \
  -f commit_id='e152d0dd6cf498467eadbeb638bf05abe11c64d4' \
  -f path='src/components/LessonNavigationButtons.tsx' \
  -F line=26 \
  -f side='RIGHT'

行番号について

line パラメーターは、ファイル内の絶対行番号ではなく、diff 内の位置を示します。

• 新規ファイルの場合：行番号はファイルの行番号と一致します
• 変更されたファイルの場合：「Files changed」タブに表示されている行番号を使用します
• 複数行コメントの場合：start_line と line を使って範囲を指定します

レスポンス

成功すると、コメントの詳細を含む JSON オブジェクトが返されます。

{
  "id": 2532291222,
  "pull_request_review_id": 3470545909,
  "path": "src/components/LessonNavigationButtons.tsx",
  "line": 26,
  "body": "Consider adding error handling here...",
  "html_url": "https://github.com/NeoLabHQ/learning-platform-app/pull/4#discussion_r2532291222",
  "created_at": "2025-11-16T22:40:46Z"
}

行を指定した複数のコメントをまとめて追加する

1 つのレビューで複数のファイルにコメントを追加するには、JSON 入力と /reviews エンドポイントを使用します。

複数のコメントにレビューを使用する理由

• アトミックな操作 - すべてのコメントがまとめて追加されます
• 通知は 1 回のみ - 複数の通知で相手に過剰な通知を送ることがありません
• 優れた UX - 一貫性のある 1 つのレビューとして表示されます
• GitHub UI と同じ仕組み - 「レビューを開始」→「レビューを完了」

基本構文

cat <<'EOF' | gh api repos/{owner}/{repo}/pulls/{pr_number}/reviews --input -
{
  "event": "COMMENT",
  "body": "Overall review summary (optional)",
  "comments": [
    {
      "path": "file1.tsx",
      "body": "Comment on file 1",
      "side": "RIGHT",
      "line": 15
    },
    {
      "path": "file2.tsx",
      "body": "Comment on file 2",
      "side": "RIGHT",
      "line": 30
    }
  ]
}
EOF

レビューイベントの種類

イベント	説明	使用する場面
COMMENT	一般的なレビューコメント	承認せずにフィードバックだけを残す場合
APPROVE	PR を承認する	変更内容に問題がなく、マージできる場合
REQUEST_CHANGES	変更を要求する	マージ前に修正が必要な問題がある場合

完全な例

cat <<'EOF' | gh api repos/NeoLabHQ/learning-platform-app/pulls/4/reviews --input -
{
  "event": "COMMENT",
  "body": "Testing multiple line-specific comments via gh api",
  "comments": [
    {
      "path": "src/components/CourseCard.tsx",
      "body": "Test comment generated by Claude",
      "side": "RIGHT",
      "line": 15
    },
    {
      "path": "src/components/CourseProgressWidget.tsx",
      "body": "Test comment generated by Claude",
      "side": "RIGHT",
      "line": 30
    },
    {
      "path": "src/components/LessonProgressTracker.tsx",
      "body": "Test comment generated by Claude",
      "side": "RIGHT",
      "line": 20
    }
  ]
}
EOF

レスポンス

{
  "id": 3470546747,
  "state": "COMMENTED",
  "html_url": "https://github.com/NeoLabHQ/learning-platform-app/pull/4#pullrequestreview-3470546747",
  "submitted_at": "2025-11-16T22:42:43Z",
  "commit_id": "e152d0dd6cf498467eadbeb638bf05abe11c64d4"
}

よくある問題と解決策

問題 1：「user_id can only have one pending review per pull request」

エラーメッセージ：

gh: Validation Failed (HTTP 422)
{"message":"Validation Failed","errors":[{"resource":"PullRequestReview","code":"custom","field":"user_id","message":"user_id can only have one pending review per pull request"}]}

原因： GitHub では、ユーザーごとに PR 1 件につき、保留中（未送信）のレビューを 1 件しか作成できません。以前に UI または API からレビューを開始して送信していない場合、新しいレビューの作成がブロックされます。

解決策 1：保留中のレビューを送信する

# Check for pending reviews
gh api repos/{owner}/{repo}/pulls/{pr_number}/reviews | jq '.[] | select(.state=="PENDING")'

# Submit it through the UI or ask the user to submit it

解決策 2：単一コメント用のエンドポイントを使用する

# Add individual comments without creating a review
gh api repos/{owner}/{repo}/pulls/{pr_number}/comments \
  -f body='Comment text' \
  -f commit_id='<sha>' \
  -f path='file.tsx' \
  -F line=26 \
  -f side='RIGHT'

問題 2：--raw-field で配列構文が機能しない

失敗した試み：

# This does NOT work - GitHub API receives an object, not an array
gh api repos/{owner}/{repo}/pulls/{pr}/reviews \
  --raw-field 'comments[0][path]=file1.tsx' \
  --raw-field 'comments[0][line]=15' \
  --raw-field 'comments[1][path]=file2.tsx' \
  --raw-field 'comments[1][line]=30'

エラー：

Invalid request. For 'properties/comments', {"0" => {...}, "1" => {...}} is not an array.

解決策： ヒアドキュメントを使って JSON 入力を渡します。

cat <<'EOF' | gh api repos/{owner}/{repo}/pulls/{pr}/reviews --input -
{
  "comments": [...]
}
EOF

問題 3：行番号が無効

エラーメッセージ：

Pull request review thread line must be part of the diff

原因： このファイルの差分に、その行番号が存在しません。

解決策：

• この PR で実際にファイルが変更されていることを確認します
• 「Files changed」タブで、差分内の実際の行番号を確認します
• 正しい commit_id（PR の最新コミット）を使用していることを確認します

問題 4：commit_id が間違っている

エラーメッセージ：

commit_sha is not part of the pull request

解決策： 最新のコミット SHA を取得します。

gh api repos/{owner}/{repo}/pulls/{pr_number} --jq '.head.sha'

ベストプラクティス

1. まず PR の情報を取得する

コメントを追加する前に、必要な情報を集めます。

# Get PR details
gh pr view {pr_number} --json headRefOid,files

# Or use the API
gh api repos/{owner}/{repo}/pulls/{pr_number} --jq '{commit: .head.sha, files: [.changed_files]}'

# List files changed
gh api repos/{owner}/{repo}/pulls/{pr_number}/files --jq '.[] | {filename: .filename, additions: .additions, deletions: .deletions}'

2. 保留中のレビューを確認する

# Check if you have a pending review
gh api repos/{owner}/{repo}/pulls/{pr_number}/reviews \
  --jq '.[] | select(.state=="PENDING" and .user.login=="YOUR_USERNAME")'

3. 意味のあるコメントを書く

• 具体的で建設的な内容にします
• ドキュメントやベストプラクティスを参照します
• 変更を求める場合は、代替案を提示します
• コードの提案にはコードブロックを使います。

Consider using async/await:

\`\`\`typescript
async function getData() {
  const result = await fetch(url);
  return result.json();
}
\`\`\`

4. 関連するコメントをまとめる

レビュー用エンドポイントを使って、関連するコメントをまとめます。

• 1 つのファイルまたは領域に対するすべてのコメント
• 特定の懸念事項（セキュリティ、パフォーマンスなど）に対するすべてのコメント
• レビューセッション全体

5. 適切なイベントタイプを選ぶ

# For feedback during development
"event": "COMMENT"

# When approving
"event": "APPROVE"

# When blocking merge
"event": "REQUEST_CHANGES"

ワークフローの例

例 1：簡単な単一コメント

#!/bin/bash
OWNER="NeoLabHQ"
REPO="learning-platform-app"
PR=4

# Get latest commit
COMMIT=$(gh api repos/$OWNER/$REPO/pulls/$PR --jq '.head.sha')

# Add comment
gh api repos/$OWNER/$REPO/pulls/$PR/comments \
  -f body='Consider extracting this into a separate function for better testability' \
  -f commit_id="$COMMIT" \
  -f path='src/utils/validation.ts' \
  -F line=45 \
  -f side='RIGHT'

例 2：包括的なレビュー

#!/bin/bash
OWNER="NeoLabHQ"
REPO="learning-platform-app"
PR=4

# Create review with multiple comments
cat <<EOF | gh api repos/$OWNER/$REPO/pulls/$PR/reviews --input -
{
  "event": "COMMENT",
  "body": "Thanks for the PR! I've reviewed the changes and have a few suggestions.",
  "comments": [
    {
      "path": "src/components/CourseCard.tsx",
      "body": "Consider memoizing this component to prevent unnecessary re-renders",
      "side": "RIGHT",
      "line": 25
    },
    {
      "path": "src/utils/courseProgress.ts",
      "body": "This function could benefit from error handling for invalid course IDs",
      "side": "RIGHT",
      "line": 12
    },
    {
      "path": "src/state/CourseProgressState.ts",
      "body": "Consider adding JSDoc comments to document the expected behavior",
      "side": "RIGHT",
      "line": 8
    }
  ]
}
EOF

例 3：複数行コメント

# Comment on a range of lines (e.g., lines 10-15)
gh api repos/$OWNER/$REPO/pulls/$PR/comments \
  -f body='This entire block could be simplified using array destructuring' \
  -f commit_id="$COMMIT" \
  -f path='src/utils/parser.ts' \
  -F start_line=10 \
  -f start_side='RIGHT' \
  -F line=15 \
  -f side='RIGHT'

便利なヘルパースクリプト

PR のファイルと行を取得する

#!/bin/bash
# pr-files.sh - List all files changed in a PR with line counts

OWNER="$1"
REPO="$2"
PR="$3"

gh api repos/$OWNER/$REPO/pulls/$PR/files --jq '.[] | "\(.filename): +\(.additions)/-\(.deletions)"'

レビューのステータスを確認する

#!/bin/bash
# check-reviews.sh - Check review status for a PR

OWNER="$1"
REPO="$2"
PR="$3"

echo "=== Reviews ==="
gh api repos/$OWNER/$REPO/pulls/$PR/reviews --jq '.[] | "\(.user.login): \(.state) at \(.submitted_at)"'

echo -e "\n=== Pending Reviews ==="
gh api repos/$OWNER/$REPO/pulls/$PR/reviews --jq '.[] | select(.state=="PENDING") | "\(.user.login): \(.state)"'

関連ドキュメント

• GitHub API：プルリクエストのレビューコメント
• GitHub API：プルリクエストのレビュー
• GitHub CLI マニュアル
• PR 作成コマンド
• コミットコマンド

API リファレンス

POST /repos/{owner}/{repo}/pulls/{pull_number}/comments

特定の行にレビューコメントを作成します。

エンドポイント： https://api.github.com/repos/{owner}/{repo}/pulls/{pull_number}/comments

パラメーター：

• body（string、必須）：コメント本文
• commit_id（string、必須）：コミットの SHA
• path（string、必須）：相対ファイルパス
• line（integer、必須）：差分内の行番号
• side（string、必須）：「LEFT」または「RIGHT」
• start_line（integer、任意）：複数行コメントの開始行
• start_side（string、任意）：複数行コメントの開始側

POST /repos/{owner}/{repo}/pulls/{pull_number}/reviews

行を指定したコメントを任意で含むレビューを作成します。

エンドポイント： https://api.github.com/repos/{owner}/{repo}/pulls/{pull_number}/reviews

パラメーター：

• event（string、必須）：「APPROVE」、「REQUEST_CHANGES」、または「COMMENT」
• body（string、任意）：レビュー全体のコメント
• comments（array、任意）：コメントオブジェクトの配列
• commit_id（string、任意）：レビュー対象のコミットの SHA

コメントオブジェクト：

• path（string、必須）：相対ファイルパス
• body（string、必須）：コメント本文
• line（integer、必須）：差分内の行番号
• side（string、必須）：「LEFT」または「RIGHT」
• start_line（integer、任意）：複数行コメントの開始行
• start_side（string、任意）：複数行コメントの開始側