GitHub、GitHub CLIで「project」コマンドを提供開始：「GitHub Projects」をより素早く、便利に使いこなせる

GitHubは、GitHub CLIの「project」コマンドの一般提供を開始した。projectコマンドにより、GitHubでの作業を計画、追跡するためのツールである「GitHub Projects」をより素早く、便利に使いこなせるという。

» 2023年07月18日 08時00分公開

[＠IT]

この記事は会員限定です。会員登録（無料）すると全てご覧いただけます。

　GitHubは2023年7月11日（米国時間）、GitHub CLIの「project」コマンドの一般提供を開始したと発表した。GitHub CLI（gh CLI）は、コマンドラインからGitHubを使用するためのオープンソースツール。projectコマンドにより、GitHubでの作業を計画、追跡するためのツールである「GitHub Projects」をより素早く、便利に使いこなせるという。

　GitHubは、GitHub Projectsの各コンポーネントに対応したprojectコマンドのサブコマンド、projectコマンドを使い始める方法、projectコマンドの実行例などを紹介した。

projectのサブコマンド

　GitHub Projectsには、「プロジェクト」「プロジェクトフィールド」「プロジェクトアイテム」という3つの主要コンポーネントがある。projectコマンドでは、これらを扱うための以下のようなサブコマンドが用意されている。

プロジェクト：create、copy、list、view
プロジェクトフィールド：field-create、field-list、field-delete
プロジェクトアイテム：item-add、item-edit、item-archive、item-list

projectコマンドを使い始める方法（権限チェック）

　新しいコマンドを使い始めるには、適切な権限を持っていることを確認する必要がある。projectコマンドにはprojectの認証スコープが必要だが、この認証スコープは、ghの認証トークンの既定のスコープには含まれていない。

　ターミナルで以下のコマンドを使って、現在のスコープをチェックできる。

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

　トークンのスコープリストにprojectがない場合は、以下のコマンドを実行し、対話型プロンプトに従って追加できる。

$ gh auth refresh -s project

　GitHub Actionsでは、projectスコープを持つトークンを使えるようにするには、ドキュメントに示されたオプションのいずれかを選択する必要がある。

projectコマンドの実行例

　GitHubは、GitHubのパブリックロードマッププロジェクト（プロジェクト番号：4747）を使用して、projectコマンドの幾つかの実行例を以下のように紹介している。

　現在のユーザーが所有するプロジェクトを一覧表示する（--ownerフラグが設定されていないことに注意）。

$ gh project list
NUMBER TITLE STATE ID
1 my first project open PVT_kwxxx
2 @mntlty's second project open PVT_kwxxx

　mntltyが所有するプロジェクトを作成する。

$ gh project create --owner mntlty --title 'my project'

　GitHubのパブリックロードマッププロジェクトを表示する。

$ gh project view --owner github 4247
Title
GitHub public roadmap
## Description
--
## Visibility
Public
## URL
<https://github.com/orgs/github/projects/4247>
## Item count
208
## Readme
--
## Field Name (Field Type)
Title (ProjectV2Field)
Assignees (ProjectV2Field)
Status (ProjectV2SingleSelectField)
Labels (ProjectV2Field)
Repository (ProjectV2Field)
Milestone (ProjectV2Field)
Linked pull requests (ProjectV2Field)
Reviewers (ProjectV2Field)
Tracks (ProjectV2Field)
Tracked by (ProjectV2Field)

　GitHubパブリックロードマッププロジェクトのアイテムを一覧表示する。

$ gh project item-list --owner github 4247
TYPE TITLE NUMBER REPOSITORY ID
Issue Kotlin security analysis support in CodeQL code scanning
(public beta) 207 github/roadmap
PVTI_lADNJr_NE13OAALQgw
Issue Swift security analysis support in CodeQL code scanning
(beta) 206 github/roadmap
PVTI_lADNJr_NE13OAALQhA
Issue Fine-grained PATs (v2 PATs) - [Public Beta]
184 github/roadmap PVTI_lADNJr_NE13OAALQmw

　GitHubパブリックロードマッププロジェクトの構造を、mntltyが所有する新しいプロジェクトにコピーする。

$ gh project copy 4247 --source-owner github --target-owner mntlty --title 'my roadmap'
https://github.com/users/mntlty/projects/1

JSONフォーマット

　projectコマンドは、JSONフォーマットで出力できる。これにより、スクリプティング、自動化、他のコマンドへのパイプで使用するために、より多くの情報を表示することが可能だ。projectのサブコマンドは全て、--format=jsonフラグを設定することで、JSONフォーマットで出力できる。

$ gh project view --owner github 4247 --format=json
{"number":4247,"url":"<https://github.com/orgs/github/projects/4247","shortDescription":"", "public":true,"closed":false,"title":"GitHub> public roadmap","id":"PVT_kwDNJr_NE10","readme":"","items":{"totalCount":208},"fields":{"totalCount":10},"owner":{"type":"Organization","login":"github"}}%

　JSONフォーマットの出力を「jq」のようなツールと組み合わせると、さらに多くの機能を引き出せる。例えば、「GitHub のパブリックロードマッププロジェクトで、ステータスが『Future』になっている全てのイシューのURLリストを作成する」といったことが可能だ。

$ gh project item-list --owner github 4247 --format=json | jq '.items[] |
select(.status=="Future" and .content.type == "Issue") | .content.url'
"<https://github.com/github/roadmap/issues/188>"
"<https://github.com/github/roadmap/issues/187>"
"<https://github.com/github/roadmap/issues/166>"

GitHub Actions

　GitHub Actionsワークフローでprojectコマンドを使うことで、GitHub Projectsをより高度に活用できる。例えば、「workflow_dispatchイベントをトリガーにして、mntltyが所有者でアイテムのないプロジェクトを全て閉じる」といったワークフローを作成できる。

on:
workflow_dispatch:
jobs:
close_empty:
runs-on: ubuntu-latest
env:
GH_TOKEN: ${{ secrets.PROJECT_TOKEN }}
steps:
- run: |
gh project list --owner mntlty --format=json \
| jq '.projects[] | select(.items.totalCount == 0) | .number' \
| xargs -n1 gh project close --owner mntlty

　ghの最新版は、GitHub Actions環境で自動的に利用できるようになる。

gh-projects拡張からのアップグレード

　projectコマンドが正式にgh CLIの一部となったことで、gh-projects拡張のリポジトリはアーカイブされた。現在、この拡張を使っている場合、何も変更する必要はない。gh-projects拡張は引き続きインストール、使用できる。gh-projects拡張からprojectコマンドへの移行は、以下のようにとても簡単だ。