github-operations

GitHub 運用

プロジェクト管理のための包括的な GitHub CLI（gh）操作です。基本的な Issue の作成から、高度な Projects v2 連携、REST API によるマイルストーンの追跡まで扱います。

概要

• GitHub Issue と PR の作成・管理
• GitHub Projects v2 のカスタムフィールドの操作
• REST API によるマイルストーン（スプリント、リリース）の管理
• gh を使った一括操作の自動化
• 複雑な操作のための GraphQL クエリの実行

---

重要：タスク管理は必須です（CC 2.1.16）

ほかの作業を始める前に、進捗を追跡するタスクを作成してください：

# 1. Create main task IMMEDIATELY
TaskCreate(
  subject="GitHub Operations: {target}",
  description="Managing GitHub issues, PRs, milestones, or Projects",
  activeForm="Managing GitHub resources"
)

# 2. Create subtasks matching the operation scope
TaskCreate(subject="Issue management", activeForm="Creating/updating issues")
TaskCreate(subject="PR management", activeForm="Managing pull requests")
TaskCreate(subject="Milestone tracking", activeForm="Updating milestones")

# 3. Set dependencies if operations are sequential
TaskUpdate(taskId="3", addBlockedBy=["2"])
TaskUpdate(taskId="4", addBlockedBy=["3"])

# 4. Update status as you progress
TaskUpdate(taskId="2", status="in_progress")  # When starting
TaskUpdate(taskId="2", status="completed")    # When done

クイックリファレンス

Issue 操作

# Create issue with labels and milestone
gh issue create --title "Bug: API returns 500" --body "..." --label "bug" --milestone "Sprint 5"

# List and filter issues
gh issue list --state open --label "backend" --assignee @me

# Edit issue metadata
gh issue edit 123 --add-label "high" --milestone "v2.0"

PR 操作

# Create PR with reviewers
gh pr create --title "feat: Add search" --body "..." --base dev --reviewer @teammate

# Watch CI status and auto-merge
gh pr checks 456 --watch
gh pr merge 456 --auto --squash --delete-branch

# Resume a session linked to a PR (CC 2.1.27)
claude --from-pr 456           # Resume session with PR context (diff, comments, review status)
claude --from-pr https://github.com/org/repo/pull/456

ヒント（CC 2.1.27）： gh pr create で作成されたセッションは、自動的に PR に関連付けられます。完全な PR コンテキストで再開するには、--from-pr を使います。

マイルストーン操作（REST API）

注意事項： gh issue edit --milestone に指定するのは番号ではなく名前（文字列）です。REST API では番号（整数）を使用します。--milestone に番号を渡さないでください。Read("references/cli-vs-api-identifiers.md") を読み込んでください。

# List milestones with progress
gh api repos/:owner/:repo/milestones --jq '.[] | "\(.title): \(.closed_issues)/\(.open_issues + .closed_issues)"'

# Create milestone with due date
gh api -X POST repos/:owner/:repo/milestones \
  -f title="Sprint 8" -f due_on="2026-02-15T00:00:00Z"

# Close milestone (API uses number, not name)
MILESTONE_NUM=$(gh api repos/:owner/:repo/milestones --jq '.[] | select(.title=="Sprint 8") | .number')
gh api -X PATCH repos/:owner/:repo/milestones/$MILESTONE_NUM -f state=closed

# Assign issues to milestone (CLI uses name, not number)
gh issue edit 123 124 125 --milestone "Sprint 8"

Projects v2 操作

# Add issue to project
gh project item-add 1 --owner @me --url https://github.com/org/repo/issues/123

# Set custom field (requires GraphQL)
gh api graphql -f query='mutation {...}' -f projectId="..." -f itemId="..."

---

JSON 出力パターン

# Get issue numbers matching criteria
gh issue list --json number,labels --jq '[.[] | select(.labels[].name == "bug")] | .[].number'

# PR summary with author
gh pr list --json number,title,author --jq '.[] | "\(.number): \(.title) by \(.author.login)"'

# Find ready-to-merge PRs (statusCheckRollup is an ARRAY, so fold it first)
gh pr list --json number,reviewDecision,statusCheckRollup \
  --jq '[.[] | select(.reviewDecision == "APPROVED"
        and ([(.statusCheckRollup // [])[] | .conclusion // .state]
             | length > 0 and all(IN("SUCCESS","SKIPPED","NEUTRAL"))))]'

---

重要な概念

マイルストーンとエピック

マイルストーン	エピック
期間ベース（スプリント、リリース）	トピックベース（機能）
期限あり	期限なし
進捗バー	タスクリストのチェックボックス
ネイティブの REST API	回避策が必要

ルール：「いつ」にはマイルストーンを、「何を」には親 Issue を使います。

Projects v2 のカスタムフィールド

Projects v2 では、カスタムフィールド（Status、Priority、Domain）の設定に GraphQL を使います。基本的な gh project コマンドでは項目の一覧表示や追加ができますが、フィールドの更新には GraphQL のミューテーションが必要です。

---

ルールのクイックリファレンス

ルール	影響	対象
issue-tracking-automation（rules/issue-tracking-automation.md を読み込む）	高	コミット、サブタスクの完了、セッションの要約からの自動進行
issue-branch-linking（rules/issue-branch-linking.md を読み込む）	中	ブランチの命名、コミット参照、PR の関連付けパターン

Issue の一括作成

複数の Issue を一度に作成する場合（例：スプリントの初期設定）は、配列を使ったループを使用します。

# Define issues as an array of "title|labels|milestone" entries
SPRINT="Sprint 9"
ISSUES=(
  "feat: Add user auth|enhancement,backend|$SPRINT"
  "fix: Login redirect loop|bug,high|$SPRINT"
  "chore: Update dependencies|maintenance|$SPRINT"
)

for entry in "${ISSUES[@]}"; do
  IFS='|' read -r title labels milestone <<< "$entry"
  NUM=$(gh issue create \
    --title "$title" \
    --label "$labels" \
    --milestone "$milestone" \
    --body "" \
    --json number --jq '.number')
  echo "Created #$NUM: $title"
done

ヒント： --json number --jq '.number' で作成した Issue 番号を取得すると、すぐに参照できます（例：Projects v2 への追加、PR での関連付け）。

---

ベストプラクティス

1. スクリプトでは必ず --json を使う - 信頼性を高めるため、--jq で解析します
2. 自動化では非対話モードを使う - --title、--body フラグを使用します
3. 一括操作の前にレート制限を確認する - gh api rate_limit。CC ≥ 2.1.116 では、gh が 403 に遭遇すると Bash ツールがトランスクリプトにレート制限のヒントを表示します。このヒントを確かな情報として扱い、処理を控えてください。何も確認せずに再試行してはいけません。2.1.116 より前は、エージェントに通知がなく、約 13 秒ですべての再試行を使い切っていました。
4. 複数行のコンテンツにはヒアドキュメントを使う - --body "$(cat <<'EOF'...EOF)"
5. PR で Issue を関連付ける - Closes #123、Fixes #456 — GitHub はマージ時に自動でクローズします
6. ISO 8601 形式の日付を使う - マイルストーンの due_on には YYYY-MM-DDTHH:MM:SSZ を使用します
7. マイルストーンは削除せず、クローズする - 履歴を保持します
8. --milestone に指定するのは番号ではなく名前 - Read("references/cli-vs-api-identifiers.md") を読み込みます
9. gh issue close を直接実行しない - gh issue comment で進捗をコメントします。Issue は、関連付けられた PR がデフォルトブランチにマージされた場合にのみクローズします

---

2026 年の CLI 変更 — 知っておくべきこと

gh-copilot 拡張機能は廃止されました

GitHub は 2025 年 10 月に gh-copilot 拡張機能を廃止しました。Copilot は現在、スタンドアロンのバイナリです。

# OLD — no longer supported
gh extension install github/gh-copilot   # fails
gh copilot suggest "revert last commit"   # fails

# NEW — standalone `copilot` binary
copilot suggest "revert last commit"
copilot explain "git rebase -i HEAD~5"

cli.github.com/copilot または Homebrew（brew install github/gh/copilot）からインストールします。両方がインストールされている場合、認証は gh auth と共有されます。

gh agent-task（2026 年）

Copilot コーディングエージェントのタスクを管理する新しいサブコマンドです。

gh agent-task create --repo owner/repo --title "Fix flaky login test"
gh agent-task list --state open
gh agent-task view 42 --log          # stream agent log
gh agent-task watch 42                # live-follow until completion
gh agent-task cancel 42

CI 主導のタスク作成には、REST エンドポイント POST /repos/{owner}/{repo}/agent-tasks と組み合わせて使います。

サブイシュー（ネイティブ機能、2026年）

サブイシューは GitHub のネイティブ機能になりました。拡張機能は不要です。

# List sub-issues of parent #123
gh api repos/{owner}/{repo}/issues/123/sub_issues

# Add an existing issue #456 as sub-issue of #123
gh api -X POST repos/{owner}/{repo}/issues/123/sub_issues \
  -f sub_issue_id=$(gh api repos/{owner}/{repo}/issues/456 --jq .node_id)

# Remove a sub-issue relationship
gh api -X DELETE repos/{owner}/{repo}/issues/123/sub_issue \
  -F sub_issue_id=<id>

従来のサードパーティ製拡張機能 gh-sub-issue も引き続き動作しますが、現在は非推奨です。GraphQL のサブイシュー変更には、引き続きイシューの node_id が必要です（references/cli-vs-api-identifiers.md を参照）。

---

関連スキル

• ork:create-pr - 適切な書式とレビュアーの割り当てでプルリクエストを作成します
• ork:review-pr - 専門エージェントによる包括的な PR レビュー
• ork:release-management - セマンティックバージョニングと変更履歴を使った GitHub リリースのワークフロー
• ork:commit - スタック型 PR のワークフローとリベースの調整は src/skills/commit/rules/（stacked-pr-workflow、stacked-pr-rebase）にあります。stacked-prs スキルはありません。
• ork:issue-progress-tracking - コミットに基づくイシューの進捗を自動更新します

主な決定事項

決定事項	選択	理由
CLI と API のどちらを使うか	gh CLI を優先	認証がより簡単で、UX が優れており、ページネーションを自動的に処理できるため
出力形式	--json と --jq	自動化での解析が安定し、正規表現による解析が不要なため
マイルストーンとエピックのどちらを使うか	期間にはマイルストーン	マイルストーンには期限と進捗バーがあり、エピックはトピックのグループ化に使うため
Projects v2 のフィールド	GraphQL の変更	gh の project コマンドには制限があり、カスタムフィールドには GraphQL が必要なため
マイルストーンのライフサイクル	削除せず、クローズする	履歴と進捗の追跡を保持できるため

上流ドキュメントの対応範囲（ここでは繰り返さないこと）

以下のトピックは公式ドキュメントに記載されています。このスキル内で内容を複製して増やすのではなく、そちらを参照してください。

トピック	ソース
gh issue による一括作成／編集／一覧表示のループ、テンプレート、移管、ピン留め	https://cli.github.com/manual/gh_issue
リポジトリ間のラベル作成／編集／複製	https://cli.github.com/manual/gh_label
組織全体のイシュー検索修飾子	https://cli.github.com/manual/gh_search_issues
マイルストーン REST CRUD：エンドポイント、ペイロードフィールド、一覧フィルターと並べ替え	https://docs.github.com/en/rest/issues/milestones
Projects v2 のフィールド変更、値のユニオン、フィールドとオプションの ID の検出	https://docs.github.com/en/issues/planning-and-tracking-with-projects/automating-your-project/using-the-api-to-manage-projects
サブイシューのエンドポイントペイロードとページネーション	https://docs.github.com/en/rest/issues/sub-issues
レート制限ヘッダー、リセットの仕様、二次制限	https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api

このスキルで引き続きすべて扱う内容： statusCheckRollup 配列の集約を含む PR のレビュー／マージ条件（references/pr-workflows.md）、GraphQL クエリ、ページネーション、ノード ID の検索（references/graphql-api.md）、マイルストーンと Projects v2 における CLI-NAME と API-NUMBER の識別子の対応（references/cli-vs-api-identifiers.md）、上記のサブイシュークイックリファレンス、レート制限の事前チェックガード（examples/automation-scripts.md）。プロジェクト固有のルールとその根拠は references/ork-delta.md にまとめています。

参考資料

Read("references/<file>") で必要に応じて読み込んでください：

ファイル	内容
ork-delta.md	プロジェクト固有のルール：フックの契約、削除せずクローズする方針、レート制限の運用、ファイルセットの契約
pr-workflows.md	レビュー、マージ戦略、自動マージ、statusCheckRollup の集約
graphql-api.md	複雑なクエリ、ページネーション、一括操作
cli-vs-api-identifiers.md	NAME と NUMBER の注意点、マイルストーン／プロジェクト ID の対応
issue-management.md	ポインタースタブ：イシューに関する差分と上流リンク
milestone-api.md	ポインタースタブ：マイルストーンに関する差分と上流リンク
projects-v2.md	ポインタースタブ：Projects v2 に関する差分と上流リンク

例

読み込み先：Read("examples/automation-scripts.md") - 長い gh ループにおけるレート制限の運用と、一括ループのレシピへのポインター