GitHub Advanced Issue Search

GitHubの高度な検索構文を使用して、AND/OR演算子とネストされたクエリを含む複雑なイシュークエリを構築・実行します。

実施すること

呼び出された際には、以下の方法で高度なイシュー検索の構築・実行をサポートします:

1. 検索リクエストを理解する - ユーザーが何を探したいのかを判断します:

   • 特定のイシュー状態、ラベル、アサイニー、作成者
   • 日付範囲と時間ベースのフィルター
   • イシュータイプ、マイルストーン、プロジェクト
   • AND/OR ロジックを使用した複雑な組み合わせ
   • 括弧を使用したネストされたクエリ

2. クエリを構築する - 以下を使用して検索を構築します:

   • ブール演算子: AND, OR
   • ネストされたクエリ: 括弧の最大5レベル
   • すべての利用可能なイシューフィールド
   • 適切なエスケープと構文

3. 実行して結果をフォーマットする - クエリを実行して結果を提示します:

   • GraphQL API(advanced_search: true付き)経由
   • REST API(advanced_searchパラメーター付き)経由
   • ウェブUI検索経由
   • 出力をフォーマット(テーブル、JSON、CSV、Markdown)

4. 必要に応じて改善する - クエリの反復を支援して目的の結果を得ます

高度な検索構文

ブール演算子

AND(暗黙的):

is:issue state:open author:alice
# すべての条件が一致する必要があります(スペースでANDが暗黙的)

AND(明示的):

is:issue AND state:open AND author:alice
# 上記と同じですが明示的

OR:

is:issue (label:bug OR label:security)
# bug OR securityラベルを持つイシューにマッチ

複雑な組み合わせ:

is:issue state:open (label:bug OR label:security) assignee:alice
# (bug OR security)ラベルを持つオープンイシュー AND aliceにアサインされたもの

ネストされたクエリ

最大5レベル深い:

is:issue state:open (
  (type:Bug OR type:Security) AND
  (assignee:alice OR assignee:bob)
)

実世界の例:

is:issue state:open (
  (label:P0 OR label:P1) AND
  (assignee:@me OR no:assignee) AND
  (milestone:"Q1 2025" OR no:milestone)
)
# 高優先度のイシュー(自分にアサインされているか未アサイン)で、
# Q1マイルストーンに含まれているかマイルストーンなし

利用可能な検索修飾子

基本的なフィルター

• is:issue - イシューのみ
• is:pr - プルリクエストのみ
• is:open / is:closed - 状態
• state:open / state:closed - 代替の状態構文

人物

• author:USERNAME - イシュー作成者
• assignee:USERNAME - アサインされたユーザー
• assignee:@me - あなたにアサインされたもの
• mentions:USERNAME - メンションされたユーザー
• commenter:USERNAME - イシューにコメントしたユーザー
• involves:USERNAME - あらゆる関わり
• no:assignee - 未アサイン

ラベル

• label:bug - bugラベルを持つ
• -label:wontfix - wontfixラベルを持たない
• no:label - ラベルなし

マイルストーンとプロジェクト

• milestone:"v2.0" - マイルストーン内
• milestone:v2.0 - 代替(スペースがなければクォート不要)
• no:milestone - マイルストーンなし
• project:BOARD_NAME - プロジェクト内

イシュータイプ(2025年新機能)

• type:Bug - Bugタイプ
• type:Epic - Epicタイプ
• type:Feature - Featureタイプ
• type:Task - Taskタイプ

日付

• created:>2025-01-01 - この日付以降に作成
• created:<2025-12-31 - この日付以前に作成
• created:2025-01-01..2025-12-31 - 日付範囲
• updated:>2025-10-01 - この日付以降に更新
• closed:2025-10-01..2025-10-15 - この範囲で クローズ

テキスト検索

• in:title - タイトルのみで検索
• in:body - 本文のみで検索
• in:comments - コメントで検索
• security in:title - タイトルに"security"を含む

カウントと制限

• comments:>10 - 10件以上のコメント
• comments:<5 - 5件未満のコメント
• comments:0 - コメントなし

リポジトリと組織

• repo:owner/name - 特定のリポジトリ
• org:organization - 組織
• user:username - ユーザーのリポジトリ

実行方法

方法1: GraphQL API(推奨)

gh api graphql -f query='
query {
  search(
    query: "is:issue state:open (type:Bug OR type:Security) assignee:@me"
    type: ISSUE
    first: 100
  ) {
    issueCount
    edges {
      node {
        ... on Issue {
          number
          title
          state
          labels(first: 10) {
            nodes {
              name
            }
          }
          assignees(first: 5) {
            nodes {
              login
            }
          }
        }
      }
    }
  }
}'

注: GraphQLの検索クエリでは高度な検索がデフォルトで有効です。

方法2: REST API

# 2025年9月4日にデフォルトになります
gh api "search/issues?q=is:issue+state:open+(type:Bug+OR+type:Security)" \
  --jq '.items[] | {number, title, state}'

# 明示的な高度な検索(2025年9月前)
gh api "search/issues?q=is:issue+state:open+(type:Bug+OR+type:Security)&advanced_search=true" \
  --jq '.items[] | {number, title, state}'

URLエンコード:

• スペース → + または %20
• 括弧 → ( および ) (通常エンコードは不要)
• クォート → %22
• コロン → : (エンコードしない)

方法3: ウェブUI

# ブラウザで検索を開く
gh issue list --web --search "is:issue state:open (type:Bug OR type:Security)"

クエリテンプレート

テンプレート1: 自分の未完了の高優先度作業

is:issue state:open assignee:@me (label:P0 OR label:P1 OR label:critical)

テンプレート2: トリアージが必要な陳腐化したイシュー

is:issue state:open no:assignee no:milestone updated:<2025-09-01

テンプレート3: 最近のバグとセキュリティイシュー

is:issue state:open (type:Bug OR type:Security) created:>2025-10-01

テンプレート4: リリースブロッカー

is:issue state:open (
  (label:blocker OR label:critical) AND
  (milestone:"v2.0" OR milestone:"v2.1")
)

テンプレート5: ピックアップ可能な未アサイン作業

is:issue state:open label:ready no:assignee (
  label:good-first-issue OR label:help-wanted
)

テンプレート6: ブロックされているまたは他をブロックしているイシュー

is:issue state:open (has:blocked-issues OR has:blocking-issues)

テンプレート7: 不完全なサブイシューを持つ親イシュー

is:issue state:open has:sub-issues -label:all-sub-issues-complete

テンプレート8: Epic/Featureの内訳

is:issue (type:Epic OR type:Feature) (
  state:open OR
  (state:closed AND closed:>2025-10-01)
)

完全なワークフロー例

例1: 今週の自分の作業を検索

QUERY="is:issue state:open assignee:@me (
  (label:P0 OR label:P1) OR
  (milestone:\"Sprint 42\" AND -label:blocked)
)"

gh api graphql -f query='
query {
  search(query: "'"$QUERY"'", type: ISSUE, first: 50) {
    issueCount
    edges {
      node {
        ... on Issue {
          number
          title
          labels(first: 5) {
            nodes {
              name
            }
          }
        }
      }
    }
  }
}' --jq '.data.search |
  "Found \(.issueCount) issues:\n" +
  (.edges | map(.node | "  #\(.number): \(.title)") | join("\n"))'

例2: 陳腐化したイシューをCSVにエクスポート

QUERY="is:issue state:open no:assignee updated:<2025-09-01"

gh api graphql -f query='
query {
  search(query: "'"$QUERY"'", type: ISSUE, first: 100) {
    edges {
      node {
        ... on Issue {
          number
          title
          createdAt
          updatedAt
          author {
            login
          }
        }
      }
    }
  }
}' --jq -r '
["Number","Title","Author","Created","Updated"],
(.data.search.edges[] | [
  .node.number,
  .node.title,
  .node.author.login,
  .node.createdAt,
  .node.updatedAt
]) | @csv' > stale-issues.csv

echo "✅ Exported to stale-issues.csv"

例3: タイプ別にイシューをカウント

for type in Bug Epic Feature Task; do
  COUNT=$(gh api "search/issues?q=is:issue+state:open+type:$type" \
    --jq '.total_count')
  echo "$type: $COUNT"
done

例4: インタラクティブなクエリビルダー

# ユーザーにフィルターを促す
echo "Build your issue search:"
read -p "State (open/closed/all): " state
read -p "Labels (comma-separated, or empty): " labels
read -p "Assignee (username or @me, or empty): " assignee
read -p "Issue type (Bug/Epic/Feature/Task, or empty): " type

# クエリを構築
QUERY="is:issue"
[[ "$state" != "all" ]] && QUERY="$QUERY state:$state"

if [[ -n "$labels" ]]; then
  IFS=',' read -ra LABEL_ARRAY <<< "$labels"
  LABEL_QUERY=$(printf "label:%s OR " "${LABEL_ARRAY[@]}")
  LABEL_QUERY=${LABEL_QUERY% OR }
  QUERY="$QUERY ($LABEL_QUERY)"
fi

[[ -n "$assignee" ]] && QUERY="$QUERY assignee:$assignee"
[[ -n "$type" ]] && QUERY="$QUERY type:$type"

echo "Query: $QUERY"
echo ""

# 実行
gh api "search/issues?q=$(echo "$QUERY" | sed 's/ /+/g')" \
  --jq '.items[] | "#\(.number): \(.title)"'

例5: よく使う検索を保存

# 検索ライブラリを作成
mkdir -p ~/.gh-searches

cat > ~/.gh-searches/my-work.sh <<'EOF'
#!/bin/bash
gh api graphql -f query='
query {
  search(
    query: "is:issue state:open assignee:@me (label:P0 OR label:P1)"
    type: ISSUE
    first: 50
  ) {
    edges {
      node {
        ... on Issue {
          number
          title
        }
      }
    }
  }
}' --jq '.data.search.edges[] | "#\(.node.number): \(.node.title)"'
EOF

chmod +x ~/.gh-searches/my-work.sh

# 保存した検索を使用
~/.gh-searches/my-work.sh

出力フォーマット

テーブル形式

gh api graphql -f query='...' --jq -r '
["Number","Title","State","Labels"],
["------","-----","-----","------"],
(.data.search.edges[] | [
  .node.number,
  .node.title,
  .node.state,
  (.node.labels.nodes | map(.name) | join(", "))
]) | @tsv' | column -t -s $'\t'

JSONエクスポート

gh api graphql -f query='...' --jq '.data.search.edges[] | .node' > results.json

Markdownチェックリスト

gh api graphql -f query='...' --jq -r '
.data.search.edges[] |
"- [ ] #\(.node.number): \(.node.title)"
' > checklist.md

重要な注記

制限事項

1. リポジトリ/組織/ユーザーフィールド - 現在、スペース区切りの場合ORフィルターとして機能(ANDではない)
2. ネストされたクエリで使用不可 - repo、org、userはまだネストされた括弧内では使用できない
3. デフォルト日付 - 2025年9月4日: 高度な検索がデフォルトになる(パラメーター不要)
4. レート制限 - 検索APIは他のエンドポイントより低いレート制限を持つ

パフォーマンスのヒント

• 特定の修飾子(リポジトリ、マイルストーンなど)を使用して結果を絞り込む
• GraphQLでfirst: Nで結果を制限
• よく使うクエリ結果をキャッシュ
• 大規模な結果セットにはページネーションを使用

エラー処理

一般的な問題:

1. 「クエリの構文エラー」

   • 括弧がバランスしているか確認
   • 演算子のスペル(AND、ORは大文字)を確認
   • 無効な修飾子がないか確認

2. 「括弧が多すぎます」

   • ネストは最大5レベル
   • クエリを簡素化するか複数の検索に分割

3. 「無効な修飾子」

   • 修飾子がサポートされているか確認(ドキュメント参照)
   • 一部のフィールドはネストされたクエリの外でのみ機能

4. 「レート制限超過」

   • 検索APIはより厳しい制限がある
   • リクエスト間に遅延を追加
   • 認証を使用して制限を増やす

ワークフローとの統合

以下と組み合わせて効果的:

• gh-issue-hierarchyスキル - サブイシューを持つ親イシューを検索
• gh-issue-dependenciesスキル - ブロックされている/ブロックしているイシューを検索
• gh-issue-typesスキル - イシュータイプでフィルター
• gh-project-manageスキル - プロジェクトに追加するイシューを検索

自動化アイデア:

• 優先作業の日次ダイジェスト
• 陳腐化したイシューのクリーンアップスクリプト
• リリースブロッカーレポート
• チームのワークロード分析
• 検索結果に基づいた自動トリアージ

使用パターン例

一般的なプロジェクト検索

優先順位を付けるべき高価値の作業:

is:issue state:open label:essential (label:enhancement OR label:bug)

注意が必要なブロックされた作業:

is:issue state:open has:blocked-issues

作業可能(未アサイン且つ準備完了):

is:issue state:open no:assignee label:ready

陳腐化したバックログアイテム:

is:issue state:open label:backlog updated:<2025-09-01

最近完了した作業:

is:issue state:closed closed:>2025-10-01 (label:config OR label:pipeline)