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両対応 |