git-gh-operations

name	git-gh-operations
description	git / gh コマンド実行時の共通エラーパターンと正しい操作方法。CWD 問題、パス解決ルール、gh CLI / GitHub API の正しい使い方、過去のエラー事例と対策を扱う。
when_to_use	git / gh コマンドでエラーが出た or 操作方法に迷うとき。Triggers: 'git add', 'git commit', 'git push', 'gh pr', 'gh api', 'GitHub操作', 'gitエラー', 'fatal:', 'pathspec'
allowed-tools	["Bash","Read"]

Git / gh 操作スキル

最重要ルール: CWD とパスの整合性

git コマンドはすべて CWD からの相対パス で解決される。 操作前に必ず pwd で CWD を確認すること。

パターン1: CWDがサブディレクトリの場合

# CWD: /work/repo/lambda-batch/MyProject/
# リポジトリルート: /work/repo/

# NG: リポジトリルートからのパスを指定
git add lambda-batch/MyProject/src/foo.py
# => fatal: pathspec did not match any files

# OK: CWDからの相対パスを指定
git add src/foo.py

# OK: 絶対パスを指定
git add /work/repo/lambda-batch/MyProject/src/foo.py

パターン2: 安全な方法

# 方法A: git -C でリポジトリルートを指定
git -C /work/repo add lambda-batch/MyProject/src/foo.py

# 方法B: CWD を変更せずに絶対パスを使用
git add "$(git rev-parse --show-toplevel)/lambda-batch/MyProject/src/foo.py"

# 方法C（推奨）: CWDからの相対パスを使用
# まず pwd で確認してからパスを組み立てる

git 操作チェックリスト

git add の前に

1. pwd で CWD を確認
2. git status で変更ファイルのパスを確認（表示されるパスはリポジトリルートからの相対パス）
3. git status の出力パスと CWD の関係を計算してから git add する

git commit の前に

1. git diff --cached でステージング内容を確認
2. HEREDOC形式でメッセージを渡す（改行・特殊文字の問題回避）

git commit -m "$(cat <<'EOF'
コミットメッセージ

Co-Authored-By: Claude Opus 4.6 <[e-mail]>
EOF
)"

gh CLI / GitHub API の注意点

パラメータ: -f vs -F

# -f: 文字列パラメータ
gh api repos/OWNER/REPO/pulls/PR/comments -f body="テキスト"

# -F: 非文字列パラメータ（数値、boolean、null、ファイル）
gh api repos/OWNER/REPO/pulls/PR/comments -F in_reply_to=2826074026

# 混在OK
gh api repos/OWNER/REPO/pulls/PR/comments -f body="返信テキスト" -F in_reply_to=2826074026

PRレビューコメントの取得

# コメント一覧を取得（id, path, body の先頭を表示）
gh api repos/OWNER/REPO/pulls/PR/comments \
  --jq '.[] | {id: .id, path: .path, body: (.body | split("\n")[0][:80])}'

PRレビューコメントへの返信

# NG: /replies エンドポイントは存在しない（404になる）
gh api repos/OWNER/REPO/pulls/comments/{id}/replies -f body='...'
# => 404 Not Found

# NG: -X POST を付けても同じ（エンドポイント自体が存在しない）
gh api -X POST repos/OWNER/REPO/pulls/comments/{id}/replies -f body='...'
# => 404 Not Found

# OK: in_reply_to パラメータを使って新規コメントとして投稿
gh api repos/OWNER/REPO/pulls/PR/comments \
  -f body="返信テキスト" \
  -F in_reply_to=COMMENT_ID

レビュースレッドの Resolve（GraphQL）

# 1. 未解決スレッドのID一覧を取得
gh api graphql -f query='
query {
  repository(owner: "OWNER", name: "REPO") {
    pullRequest(number: PR) {
      reviewThreads(first: 50) {
        nodes {
          id
          isResolved
          comments(first: 1) {
            nodes { path body }
          }
        }
      }
    }
  }
}' --jq '.data.repository.pullRequest.reviewThreads.nodes[] | select(.isResolved == false) | {id, path: .comments.nodes[0].path}'

# 2. スレッドを Resolve
gh api graphql -f query='
mutation {
  resolveReviewThread(input: {threadId: "PRRT_xxx"}) {
    thread { isResolved }
  }
}'

PR の CI チェック結果

gh pr checks は1つでもfailがあると exit code 1 で終了する。 Claude Codeではコマンド失敗と判定されて処理が止まるため、必ず || true を付ける。

# NG: failがあるとexit code 1で止まる
gh pr checks PR --repo OWNER/REPO

# OK: exit codeを常に0にして出力を取得
gh pr checks PR --repo OWNER/REPO 2>&1 || true

# OK: 失敗のみフィルタ
gh pr checks PR --repo OWNER/REPO 2>&1 | grep -i fail || true

重要: CIの完了を待ってはいけない

• --watch や完了までのポーリングは 禁止。現在のステータスを一度スナップショットするだけでよい。
• チェックが in_progress / queued / pending の場合は 完了を待たず次のステップへ進む。
• 対応対象は コード修正で直せるfailのみ。以下のような「ステータス確認系」チェックは無視する:
  • check_pr_requirements 等、PR要件・メタ情報のみ検証するもの
  • Lint/テストに非依存なラベル/タイトル/説明チェック
  • 外部サービス起因で自己修復するトランジェントなfail（再実行で直るもの）
• 対応する: ビルド失敗・テスト失敗・型エラー・lint違反など、リポジトリ内コードの修正で解消可能なもの。

# 失敗ジョブのログ（エラー行のみ抽出）
gh run view RUN_ID --repo OWNER/REPO --log-failed 2>&1 \
  | grep -E '(FAIL|Error|Tests:)' | head -20 || true

自分のPRは Approve できない

# GitHub の制約: 自分で作成した PR に APPROVE レビューは不可
# => "Can not approve your own pull request"
# 対策: event を "COMMENT" に変更して送信

PR作成時の body は HEREDOC

# NG: \n がリテラルで混入する可能性
gh pr create --title "タイトル" --body "行1\n行2"

# OK: HEREDOC形式
gh pr create --title "タイトル" --body "$(cat <<'EOF'
## Summary
- 変更内容

## Test plan
- [ ] テスト項目
EOF
)"

AWS CLI の注意点

CloudWatch ログストリーム名の [$LATEST]

# NG: --query で [$LATEST] を含む文字列がパースエラー
aws logs get-log-events --query 'events[*].message' --output text

# OK: --output json にして python でパース
aws logs get-log-events --output json | python3 -c "
import sys,json
data = json.loads(sys.stdin.read())
for e in data['events']:
    print(e['message'].strip())
"

エラー事例集

エラーメッセージ	原因	対策
fatal: pathspec '...' did not match any files	CWD とパスの不一致	pwd 確認後、CWD相対パスで指定
404 Not Found (gh api replies)	/comments/{id}/replies は存在しない	in_reply_to パラメータで投稿
422 Unprocessable (gh api)	-f で数値を渡した	数値は -F を使う
Can not approve your own pull request	自己 Approve 不可	COMMENT イベントに変更
gh pr checks が exit code 1	1つでもfailがあると非0終了	gh pr checks ... 2>&1 || true
Unknown options: , , , (aws cli)	[$LATEST] のシェルエスケープ	--output json + python パース

詳細ガイド

ファイル	内容	参照タイミング
01-common-errors.md	詳細なエラー事例と再現手順	エラー発生時