syncing-github-project

name	syncing-github-project
description	リリース計画を GitHub Project・Issue・Milestone に反映し一元管理。初回の一括同期から差異検出・自動同期まで対応する。「GitHub Project に同期したい」「Issue を作成したい」「計画と GitHub の差異を確認したい」「Milestone を設定したい」といった場面で発動する。計画ドキュメントを Single Source of Truth とし GitHub に自動反映することで、二重管理の手間と不整合を排除する。

GitHub Project 同期

リリース計画を GitHub Project・Issue・Milestone に反映し、プロジェクト管理を GitHub 上で一元化する。

docs/development/release_plan.md を正とし、GitHub は同期先として扱う。手動で GitHub を直接更新するのではなく、計画ドキュメントを更新してから --sync で反映する。

オプション

オプション	説明
なし	全体の同期を実行（Project・Issue・フィールド・Milestone）
--project	GitHub Project のみを作成
--issues	Issue のみを作成（Project 存在が前提）
--fields	各 Issue に対して Project フィールド値を設定
--milestones	Milestone のみを作成し Issue に割り当て
--sync	release_plan.md と GitHub の差異を確認し同期
--status	現在の GitHub Project 状態を表示

GitHub Project の作成

release_plan.md に基づいて Project を作成し、カスタムフィールドを設定する。

標準フィールド構成:

フィールド	タイプ	説明
Status	Single Select	Todo / In Progress / Done
リリース	Single Select	release_plan.md のリリースフェーズに対応
優先度	Single Select	ストーリーの優先度
SP	Number	ストーリーポイント
イテレーション	Iteration	スプリント期間（開始日・期間付き）

# Single Select フィールドの作成
gh project field-create <PROJECT_NUMBER> --owner <OWNER> \
  --name "<フィールド名>" --data-type "SINGLE_SELECT" \
  --single-select-options "<選択肢1>,<選択肢2>"

# Number フィールドの作成
gh project field-create <PROJECT_NUMBER> --owner <OWNER> \
  --name "SP" --data-type "NUMBER"

Issue の作成

ユーザーストーリーを GitHub Issue として作成し、Project に追加する。

• タイトル: [ストーリーID] ストーリー名
• 本文: ユーザーストーリー、サブタスク、受入条件、見積もり情報
• Milestone: リリースフェーズに対応する Milestone に割り当て

gh issue create --repo <OWNER>/<REPO> \
  --title "<ストーリーID>: <ストーリー名>" \
  --milestone "<Milestone 名>" --body "..."

gh project item-add <PROJECT_NUMBER> --owner <OWNER> \
  --url "https://github.com/<OWNER>/<REPO>/issues/<NUMBER>"

Iteration フィールドの作成と設定

Iteration フィールドは Single Select ではなく Iteration 型 で作成する。GraphQL API で iterationConfiguration を含めることで、フィールド作成と同時にイテレーション期間を設定できる。

# Iteration フィールドの作成
gh api graphql -f query='
mutation {
  createProjectV2Field(input: {
    projectId: "<PROJECT_ID>"
    dataType: ITERATION
    name: "イテレーション"
    iterationConfiguration: {
      startDate: "<開始日 YYYY-MM-DD>"
      duration: <デフォルト期間（日数）>
      iterations: [
        { title: "<IT名>", startDate: "<開始日>", duration: <日数> }
      ]
    }
  }) { projectV2Field { ... on ProjectV2IterationField { id } } }
}'

# 各 Issue への Iteration 値の設定
gh api graphql -f query='
mutation {
  updateProjectV2ItemFieldValue(input: {
    projectId: "<PROJECT_ID>"
    itemId: "<ITEM_ID>"
    fieldId: "<ITERATION_FIELD_ID>"
    value: { iterationId: "<ITERATION_ID>" }
  }) { projectV2Item { id } }
}'

差異確認と同期（--sync）

release_plan.md と GitHub の整合性を確認し、差異があれば同期を実行する。

確認項目: ストーリー数、SP、リリース/Milestone 割り当て、優先度、イテレーション割り当て、Status

同期動作:

• 新規ストーリー: Issue を作成し Project に追加する
• 変更されたストーリー: Issue のフィールド値を更新する
• 削除されたストーリー: Issue をクローズする（削除はしない）

同期フロー

graph TD
    A[release_plan.md] --> B{同期開始}
    B --> C[GitHub Project 作成]
    C --> D[カスタムフィールド設定]
    D --> E[Issue 作成]
    E --> F[Project に Item 追加]
    F --> G[フィールド値設定]
    G --> H[Milestone 作成・割当]
    H --> I[同期完了]

途中から再開

同期作業の途中から再開する場合は、まず現在の GitHub 状態を確認する。

Example:

ユーザー: 「Project と Issue は作成済み。フィールド値を設定したい」
回答: --status で現在の GitHub 状態を確認する。
      --fields でフィールド値を一括設定する。
      設定後に --sync で release_plan.md との整合性を検証する。

注意事項

• docs/development/release_plan.md が存在すること、gh CLI がインストールされ認証済みであること、Project API スコープが有効であること（前提条件）
• 既存の Project/Issue がある場合は重複作成に注意する
• Iteration フィールドの期間変更は GraphQL API または Web UI で実施する
• 初回は --sync で差異確認してから同期する。大規模変更前にはバックアップを推奨する

関連スキル

• planning-releases — リリース計画とイテレーション計画の作成
• tracking-progress — 進捗状況の確認と更新
• orchestrating-project — 計画・進捗管理フェーズ全体のオーケストレーション
• git-commit — 変更のコミット