GitHub CLI project command が一般利用可能になりました

こんにちは、CX事業本部 Delivery部の若槻です。

GitHub projects は、Issue や Pull Request と統合的に利用できるプロジェクト管理機能です。

今までは projects を API で管理したい場合は GraphQL API を使用する必要がありましたが、このたびの GitHub CLI のアップデートにより projects command が一般利用可能（GA）となり、CLI から projects が管理ができるようになりました。

利用可能になったコマンド

今回利用可能になった projects command は以下となります。

• gh project close
• gh project copy
• gh project create
• gh project delete
• gh project edit
• gh project field-create
• gh project field-delete
• gh project field-list
• gh project item-add
• gh project item-archive
• gh project item-create
• gh project item-delete
• gh project item-edit
• gh project item-list
• gh project list
• gh project view

大きく分けて、projects 自体を管理するコマンド、projects 内のカードを管理するコマンド、およびカードのフィールドを管理するコマンドの3種類です。

コマンド一覧は下記から確認できます。

試してみる

権限の設定

まず、projects command を使用するためには GitHub の認証トークンに権限スコープ project が設定されている必要があります。

試しに project list コマンドを実行すると、read:project スコープが足りない旨のエラーが表示されます。

$ gh project list  
error: your authentication token is missing required scopes [read:project]
To request it, run:  gh auth refresh -s read:project

認証ステータスを確認すると、Token scopes に project が設定されていません。

$ gh auth status
github.com
  ✓ Logged in to github.com as cm-rwakatsuki (/Users/wakatsuki.ryuta/.config/gh/hosts.yml)
  ✓ Git operations for github.com configured to use https protocol.
  ✓ Token: gho_************************************
  ✓ Token scopes: gist, read:org, repo, workflow

gh auth refresh コマンドで project スコープを追加します。

gh auth refresh -s project

再度認証ステータスを確認すると、Token scopes に project が設定されていることが確認できました。

$ gh auth status
github.com
  ✓ Logged in to github.com as cm-rwakatsuki (keyring)
  ✓ Git operations for github.com configured to use https protocol.
  ✓ Token: gho_************************************
  ✓ Token scopes: gist, project, read:org, repo, workflow

project list コマンドも実行できるようになりました。

$ gh project list
NUMBER  TITLE                     STATE  ID
4       test project              open   PVT_kwHOA2ucV84AGIFl
3       DevIO Neta                open   PVT_kwHOA2ucV84AEG5E

アイテムの操作

projects command で最も行いたいであろうアイテムの操作を試してみます。

アイテムの追加

まず、gh project list コマンドで操作したい project の NUMBER を予め確認しておきます。

アイテムを project に追加する場合は、gh project item-add コマンドを使用します。先程 gh project list コマンドで確認した project の NUMBER により追加先の project を指定します。--owner では、追加先の project の owner 、--url では、追加するアイテムの URL を指定します。

gh project item-add 4 --owner "@me" --url https://github.com/cm-rwakatsuki/test/issues/5

注意点として、draft issue の追加はできないようです。

アイテム一覧の取得

アイテムの一覧は gh project item-list コマンドで取得できます。project の NUMBER および owner を指定します。

$ gh project item-list 4 --owner "@me"
TYPE        TITLE                 NUMBER  REPOSITORY          ID
Issue       デバッグ対応          2       cm-rwakatsuki/test  PVTI_lAHOA2ucV84AGIFlzgCiJl0
Issue       ボタンの配置を変更    3       cm-rwakatsuki/test  PVTI_lAHOA2ucV84AGIFlzgFjPTY
DraftIssue  ログ監視ツールの検討                              PVTI_lAHOA2ucV84AGIFlzgFjPUw
DraftIssue  ドキュメント修正                                  PVTI_lAHOA2ucV84AGIFlzgFjPVM
DraftIssue  APIの実装                                         PVTI_lAHOA2ucV84AGIFlzgGavco
Issue       API 実装              5       cm-rwakatsuki/test  PVTI_lAHOA2ucV84AGIFlzgH632s

ステータスは分からない点には注意です。project item-view コマンドがあっても良さそうなのですが、まだ実装されていませんでした。

フィールド一覧の取得

フィールドの一覧は gh project field-list コマンドで取得できます。project の NUMBER および owner を指定します。

$ gh project field-list 4 --owner "@me"
NAME                  DATA TYPE                   ID
Title                 ProjectV2Field              PVTF_lAHOA2ucV84AGIFlzgDh-dU
Assignees             ProjectV2Field              PVTF_lAHOA2ucV84AGIFlzgDh-dY
Status                ProjectV2SingleSelectField  PVTSSF_lAHOA2ucV84AGIFlzgDh-dc
Labels                ProjectV2Field              PVTF_lAHOA2ucV84AGIFlzgDh-dg
Linked pull requests  ProjectV2Field              PVTF_lAHOA2ucV84AGIFlzgDh-dk
Reviewers             ProjectV2Field              PVTF_lAHOA2ucV84AGIFlzgDh-ds
Repository            ProjectV2Field              PVTF_lAHOA2ucV84AGIFlzgDh-dw
Milestone             ProjectV2Field              PVTF_lAHOA2ucV84AGIFlzgDh-d0
New Field             ProjectV2Field              PVTF_lAHOA2ucV84AGIFlzgJ455o

これにより、例えばアイテムのステータスをコマンドで更新したい場合は ID PVTSSF_lAHOA2ucV84AGIFlzgDh-dc を指定すれば良いことが分かります。

アイテムの編集

アイテムの編集は gh project item-edit コマンドで行います。ワークフロー自動化のために最も使われるであろうコマンドだと思われますが、現状ではいくつか制限がありました。

draft issue の編集ができない

draft issue のタイトルを変更しようとすると、以下のようなエラーが表示されました。

$ gh project item-edit \
  --id "PVTI_lAHOA2ucV84AGIFlzgFjPUw" \
  --field-id "PVTSSF_lAHOA2ucV84AGIFlzgDh-dc" \
  --project-id "PVT_kwHOA2ucV84AGIFl" \
  --title "hoge"
ID must be the ID of the draft issue content which is prefixed with `DI_`

project list で確認した際は操作したい draft issue の ID は PVTI_ から始まる値だったのですが、DI_ で始まる ID を指定せよとのことです。よって draft issue を編集する方法が分かりませんでした。

ステータスの編集ができない

issue のステータスを変更しようとすると、以下のようなエラーが表示されました。

$ gh project item-edit \
  --id "PVTI_lAHOA2ucV84AGIFlzgFjPUw" \
  --field-id "PVTSSF_lAHOA2ucV84AGIFlzgDh-dc" \
  --project-id "PVT_kwHOA2ucV84AGIFl" \
  --single-select-option-id "Done"
GraphQL: The single select option Id does not belong to the field (updateProjectV2ItemFieldValue)

上記の single-select-option-id プロパティで指定したのは、ステータスの ID ではなく名前です。どうやら ID を指定する必要があるようですが、その ID の確認方法が分かりませんでした。

おわりに

GitHub CLI project command が一般利用可能になったので試してみました。

現状ではアイテムの編集方法が分からず、特に draft issue の操作ができないのは残念でした。もし分かる方がいれば教えてくださると助かります。

以上