github-projects

GitHub Projects CLI

gh project コマンドを使用して GitHub Projects（v2）を管理します。project スコープが必要です。gh auth refresh -s project で追加できます。

前提条件

認証に project スコープが含まれていることを確認します。

gh auth status  # Check current scopes
gh auth refresh -s project  # Add project scope if missing

ゲート（破壊的操作および影響の大きい操作）

project close、project unlink、item-archive、item-delete、field-delete などのコマンドは、データを変更または削除します。以前のターンでの記憶に頼らず、順を追って確認してください。

1. 合格： gh project view PROJECT_NUM --owner OWNER（または gh project list --owner OWNER --format json）を実行し、タイトル（または JSON の title）が対象のプロジェクトと一致することを確認します。
2. 合格： アイテムやフィールドの場合、ITEM_ID、FIELD_ID、PROJECT_ID、オプション ID は、このセッション内で実行した gh project item-list … --format json または gh project field-list … --format json の結果からのみ設定します。推測した値、途中で切り詰められた値、無関係な出力からコピーした値は使用しないでください。
3. その後： 破壊的なサブコマンドを実行します。

一括追加（パイプライン）

1. 合格： 1 つの --url に対して gh project item-add を 1 回実行し、複数の URL に xargs やループを使う前に、アイテムが gh project item-list … --format json（または UI）に表示されることを確認します。

クイックリファレンス

プロジェクトの一覧表示と表示

# List your projects
gh project list

# List org projects (including closed)
gh project list --owner ORG_NAME --closed

# View project details
gh project view PROJECT_NUM --owner OWNER

# Open in browser
gh project view PROJECT_NUM --owner OWNER --web

# JSON output with jq filtering
gh project list --format json | jq '.projects[] | {number, title}'

プロジェクトの作成と編集

# Create project
gh project create --owner OWNER --title "Project Title"

# Edit project
gh project edit PROJECT_NUM --owner OWNER --title "New Title"
gh project edit PROJECT_NUM --owner OWNER --description "New description"
gh project edit PROJECT_NUM --owner OWNER --visibility PUBLIC

# Close/reopen project
gh project close PROJECT_NUM --owner OWNER
gh project close PROJECT_NUM --owner OWNER --undo  # Reopen

プロジェクトをリポジトリにリンク

# Link to repo
gh project link PROJECT_NUM --owner OWNER --repo REPO_NAME

# Link to team
gh project link PROJECT_NUM --owner ORG --team TEAM_NAME

# Unlink
gh project unlink PROJECT_NUM --owner OWNER --repo REPO_NAME

プロジェクトのアイテム

既存の Issue／PR を追加

# Add issue to project
gh project item-add PROJECT_NUM --owner OWNER --url https://github.com/OWNER/REPO/issues/123

# Add PR to project
gh project item-add PROJECT_NUM --owner OWNER --url https://github.com/OWNER/REPO/pull/456

下書きアイテムを作成

gh project item-create PROJECT_NUM --owner OWNER --title "Draft item" --body "Description"

アイテムを一覧表示

# List items (default 30)
gh project item-list PROJECT_NUM --owner OWNER

# List more items
gh project item-list PROJECT_NUM --owner OWNER --limit 100

# JSON output
gh project item-list PROJECT_NUM --owner OWNER --format json

アイテムを編集

アイテムは ID（item-list --format json で取得）を指定して編集します。

# Edit draft issue title/body
gh project item-edit --id ITEM_ID --title "New Title" --body "New body"

# Update field value (requires field-id and project-id)
gh project item-edit --id ITEM_ID --project-id PROJECT_ID --field-id FIELD_ID --text "value"
gh project item-edit --id ITEM_ID --project-id PROJECT_ID --field-id FIELD_ID --number 42
gh project item-edit --id ITEM_ID --project-id PROJECT_ID --field-id FIELD_ID --date "2024-12-31"
gh project item-edit --id ITEM_ID --project-id PROJECT_ID --field-id FIELD_ID --single-select-option-id OPTION_ID
gh project item-edit --id ITEM_ID --project-id PROJECT_ID --field-id FIELD_ID --iteration-id ITER_ID

# Clear field value
gh project item-edit --id ITEM_ID --project-id PROJECT_ID --field-id FIELD_ID --clear

アイテムをアーカイブ／削除

gh project item-archive PROJECT_NUM --owner OWNER --id ITEM_ID
gh project item-delete PROJECT_NUM --owner OWNER --id ITEM_ID

プロジェクトのフィールド

フィールドを一覧表示

gh project field-list PROJECT_NUM --owner OWNER
gh project field-list PROJECT_NUM --owner OWNER --format json

フィールドを作成

# Text field
gh project field-create PROJECT_NUM --owner OWNER --name "Notes" --data-type TEXT

# Number field
gh project field-create PROJECT_NUM --owner OWNER --name "Points" --data-type NUMBER

# Date field
gh project field-create PROJECT_NUM --owner OWNER --name "Due Date" --data-type DATE

# Single select with options
gh project field-create PROJECT_NUM --owner OWNER --name "Priority" \
  --data-type SINGLE_SELECT \
  --single-select-options "Low,Medium,High,Critical"

フィールドを削除

gh project field-delete --id FIELD_ID

一般的なワークフロー

Issue を追加してステータスを設定

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

# 2. Get item ID and field IDs
gh project item-list 1 --owner "@me" --format json | jq '.items[-1]'
gh project field-list 1 --owner "@me" --format json

# 3. Update status field
gh project item-edit --id ITEM_ID --project-id PROJECT_ID \
  --field-id STATUS_FIELD_ID --single-select-option-id OPTION_ID

Issue を一括追加

# Add all open issues from a repo
gh issue list --repo owner/repo --state open --json url -q '.[].url' | \
  xargs -I {} gh project item-add 1 --owner "@me" --url {}

JSON 出力と jq のパターン

# Get project IDs
gh project list --format json | jq '.projects[] | {number, id, title}'

# Get field IDs and options
gh project field-list 1 --owner "@me" --format json | jq '.fields[] | {id, name, options}'

# Get item IDs with field values
gh project item-list 1 --owner "@me" --format json | jq '.items[] | {id, title, fieldValues}'

# Filter items by status
gh project item-list 1 --owner "@me" --format json | \
  jq '.items[] | select(.status == "In Progress")'

リファレンスファイル

• items.md：アイテム管理、フィールド値の編集、一括操作
• fields.md：フィールドの種類、カスタムフィールドの作成、オプション管理

コマンド概要

コマンド	用途
project list	プロジェクトを一覧表示
project view	プロジェクトの詳細を表示
project create	新しいプロジェクトを作成
project edit	プロジェクトの設定を変更
project close	プロジェクトを閉じる／再開する
project link/unlink	リポジトリ／チームに接続
project item-add	既存の Issue／PR を追加
project item-create	下書きアイテムを作成
project item-list	プロジェクトのアイテムを一覧表示
project item-edit	アイテムのフィールドを更新
project item-archive	アイテムをアーカイブ
project item-delete	アイテムを削除
project field-list	プロジェクトのフィールドを一覧表示
project field-create	カスタムフィールドを追加
project field-delete	フィールドを削除