github-issue-dependency

name	github-issue-dependency
description	GitHub Issue間の依存関係（Is blocking / Blocked by）を設定・取得するためのAPI操作を提供

GitHub Issue依存関係管理

参照元: decompose-issue.md, subtask-detection.md から利用される依存関係管理スキル

---

概要

GitHub Issue間の「ブロック関係」を管理する機能。2025年8月にGA（一般提供）となった。

用語:

• Is blocking: このIssueが他のIssueの着手をブロックしている
• Blocked by: このIssueが他のIssueによってブロックされている

Reference: https://docs.github.com/en/rest/issues/issue-dependencies

---

CLIスクリプト

自動化スクリプトが利用可能です：

# 依存関係を追加（#10 は #5 にブロックされている）
bash .opencode/skill/github-issue-dependency/scripts/issue-dependency.sh add-blocked-by 10 5

# 依存関係を削除
bash .opencode/skill/github-issue-dependency/scripts/issue-dependency.sh remove-blocked-by 10 5

# 依存関係を一覧表示
bash .opencode/skill/github-issue-dependency/scripts/issue-dependency.sh list 10

コマンド	引数	説明
add-blocked-by	<issue> <blocking-issue>	Issue が blocking-issue にブロックされていることを設定
remove-blocked-by	<issue> <blocking-issue>	ブロック関係を削除
list	<issue>	Issue の依存関係を一覧表示

---

REST API

依存関係追加（Blocked by）

# 前提: Issue番号からdatabase IDを取得する必要がある

# 1. blocking Issue の database ID を取得
BLOCKING_ISSUE_ID=$(gh api "repos/{owner}/{repo}/issues/{blocking_number}" --jq '.id')

# 2. 依存関係を追加
gh api "repos/{owner}/{repo}/issues/{issue_number}/dependencies/blocked_by" \
  -X POST \
  -f "issue_id=${BLOCKING_ISSUE_ID}"

依存関係削除

# blocking Issue の database ID が必要
gh api "repos/{owner}/{repo}/issues/{issue_number}/dependencies/blocked_by/{blocking_issue_id}" \
  -X DELETE

依存関係取得

# このIssueをブロックしているIssue一覧
gh api "repos/{owner}/{repo}/issues/{issue_number}/dependencies/blocked_by" \
  --jq '.[] | {number, title, state}'

# このIssueがブロックしているIssue一覧
gh api "repos/{owner}/{repo}/issues/{issue_number}/dependencies/blocking" \
  --jq '.[] | {number, title, state}'

---

GraphQL API

REST APIの代わりにGraphQL APIも使用可能。Node IDを使用する。

依存関係追加

# 1. Node ID を取得
ISSUE_NODE_ID=$(gh issue view 10 --json id --jq '.id')
BLOCKING_NODE_ID=$(gh issue view 5 --json id --jq '.id')

# 2. 依存関係を追加
gh api graphql -f query='
  mutation($issueId: ID!, $blockingIssueId: ID!) {
    addBlockedBy(input: {
      issueId: $issueId,
      blockingIssueId: $blockingIssueId
    }) {
      issue {
        id
        number
        title
      }
    }
  }
' -f issueId="$ISSUE_NODE_ID" -f blockingIssueId="$BLOCKING_NODE_ID"

依存関係取得（GraphQL）

gh api graphql -f query='
  query($owner: String!, $name: String!, $number: Int!) {
    repository(owner: $owner, name: $name) {
      issue(number: $number) {
        id
        title
        blockedBy(first: 50) {
          nodes {
            number
            title
            state
          }
        }
        blocking(first: 50) {
          nodes {
            number
            title
            state
          }
        }
        issueDependenciesSummary {
          totalBlockedBy
          totalBlocking
        }
      }
    }
  }
' -f owner="OWNER" -f name="REPO" -F number=10

---

処理フロー（Subtask作成時）

def add_subtask_dependencies(parent_id: int, subtask_ids: list[int], dependencies: dict[int, list[int]]) -> None:
    """
    Subtask作成後に依存関係を設定する
    
    Args:
        parent_id: 親Issue番号
        subtask_ids: 作成されたSubtaskのIssue番号リスト
        dependencies: {subtask_id: [depends_on_ids]} の依存関係マップ
    """
    for subtask_id, deps in dependencies.items():
        for dep_id in deps:
            if dep_id in subtask_ids:  # 同じ親の子Issue間のみ
                # subtask_id は dep_id にブロックされている
                bash(f'''
                    bash .opencode/skill/github-issue-dependency/scripts/issue-dependency.sh \
                      add-blocked-by {subtask_id} {dep_id}
                ''')

---

エラーハンドリング

エラー	対応
Issue ID取得失敗	警告ログ出力してスキップ
API呼び出し失敗	リトライ1回後スキップ（致命的エラーとしない）
循環依存の検出	API側でエラー → 警告表示してスキップ
既に依存関係が存在	成功として扱う（冪等性）

重要: 依存関係設定の失敗はワークフロー全体を停止させない。Issue自体は作成済みなので、手動で依存関係を設定可能。

---

使用箇所

ワークフロー	用途
/decompose-issue	分割したSubtask間の依存関係を設定
subtask-detection	依存関係を考慮した実行順序の決定
/detailed-design-workflow	作成したIssue間の依存関係を設定

---

制限事項

制限	値
1 Issue あたりの最大依存関係数	50件（blocked by / blocking 各）
クロスリポジトリ	非対応（同一リポジトリ内のみ）

---

変更履歴

日付	変更内容
2026-01-25	初版作成。REST API / GraphQL API両対応