GitHubは、GitHub CLIの「project」コマンドの一般提供を開始した。projectコマンドにより、GitHubでの作業を計画、追跡するためのツールである「GitHub Projects」をより素早く、便利に使いこなせるという。
この記事は会員限定です。会員登録(無料)すると全てご覧いただけます。
GitHubは2023年7月11日(米国時間)、GitHub CLIの「project」コマンドの一般提供を開始したと発表した。GitHub CLI(gh CLI)は、コマンドラインからGitHubを使用するためのオープンソースツール。projectコマンドにより、GitHubでの作業を計画、追跡するためのツールである「GitHub Projects」をより素早く、便利に使いこなせるという。
GitHubは、GitHub Projectsの各コンポーネントに対応したprojectコマンドのサブコマンド、projectコマンドを使い始める方法、projectコマンドの実行例などを紹介した。
GitHub Projectsには、「プロジェクト」「プロジェクトフィールド」「プロジェクトアイテム」という3つの主要コンポーネントがある。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スコープを持つトークンを使えるようにするには、ドキュメントに示されたオプションのいずれかを選択する必要がある。
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
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ワークフローで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環境で自動的に利用できるようになる。
projectコマンドが正式にgh CLIの一部となったことで、gh-projects拡張のリポジトリはアーカイブされた。現在、この拡張を使っている場合、何も変更する必要はない。gh-projects拡張は引き続きインストール、使用できる。gh-projects拡張からprojectコマンドへの移行は、以下のようにとても簡単だ。
ただし、GitHubは、混乱を避けるために、以下のコマンドを実行し、gh-projects拡張を削除することも推奨している。
$ gh ext remove gh-projects
Copyright © ITmedia, Inc. All Rights Reserved.