GitHub CLI 拡張機能について
GitHub CLI 拡張機能は、だれでも作成して使用できる、カスタム GitHub CLI コマンドです。GitHub CLI 拡張機能の使用方法について詳しくは、「GitHub CLI 拡張機能の使用」をご覧ください。
作成する拡張機能ごとにリポジトリが必要です。 リポジトリ名は gh-
で始まる必要があります。 リポジトリ名の残りの部分は拡張機能の名前です。 リポジトリのルートには、リポジトリと同じ名前の実行可能ファイル、またはリリースにアタッチされたプリコンパイル済みバイナリ実行可能ファイルのセットが必要です。
Note
実行可能スクリプトに依存する場合は、bash スクリプトを使用することをお勧めします。bash は広く利用できるインタープリターであるためです。 bash 以外のスクリプトを使用できますが、拡張機能を使用するには、ユーザーに必要なインタープリターがインストールされている必要があります。 インタープリターがインストールされているユーザーに依存しない場合は、プリコンパイル済み拡張機能を検討してください。
gh extension create
で解釈される拡張機能を作成する
Note
引数なしで gh extension create
を実行すると、対話型ウィザードが開始されます。
gh extension create
コマンドを使用して、いくつかのスタート コードを含む bash スクリプトを含む拡張機能のプロジェクトを作成できます。
-
gh extension create
サブコマンドを使用して、新しい拡張機能を設定します。EXTENSION-NAME
は、お使いの拡張機能の名前に置き換えます。gh extension create EXTENSION-NAME
-
表示された指示に従って、拡張機能を最終処理し、必要に応じて公開します。
gh extension create
を使用して Go でプリコンパイル済み拡張機能を作成する
--precompiled=go
引数を使用すると、Go スキャフォールディング、ワークフロー スキャフォールディング、スタート コードなど、拡張機能の Go ベースのプロジェクトを作成できます。
-
gh extension create
サブコマンドを使用して、新しい拡張機能を設定します。EXTENSION-NAME
は、お使いの拡張機能の名前に置き換えて、--precompiled=go
を指定します。gh extension create --precompiled=go EXTENSION-NAME
-
表示された指示に従って、拡張機能を最終処理し、必要に応じて公開します。
gh extension create
を使用して Go 以外のプリコンパイル済み拡張機能を作成する
--precompiled=other
引数を使用すると、ワークフロー スキャフォールディングなど、Go 以外のプリコンパイル済み拡張機能のプロジェクトを作成できます。
-
gh extension create
サブコマンドを使用して、新しい拡張機能を設定します。EXTENSION-NAME
は、お使いの拡張機能の名前に置き換えて、--precompiled=other
を指定します。gh extension create --precompiled=other EXTENSION-NAME
-
選択したコンパイル済み言語に拡張機能の初期コードをいくつか追加します。
-
拡張機能を自動的にビルドできるように、
script/build.sh
に拡張機能をビルドするコードを入力します。 -
表示された指示に従って、拡張機能を最終処理し、必要に応じて公開します。
解釈される拡張機能を手動で作成する
-
gh-EXTENSION-NAME
というローカル ディレクトリを作成し、拡張機能用に使用します。EXTENSION-NAME
は、お使いの拡張機能の名前に置き換えます。 たとえば、gh-whoami
のようにします。 -
作成したディレクトリに、ディレクトリと同じ名前の実行可能ファイルを追加します。
Note
ファイルが実行可能であることを確認します。 UNIX では、コマンド ラインで
chmod +x file_name
を実行して、file_name
を実行可能にできます。 Windows では、git init -b main
、git add file_name
、そしてgit update-index --chmod=+x file_name
を実行できます。 -
実行可能ファイルにスクリプトを記述します。 たとえば次のような点です。
#!/usr/bin/env bash set -e exec gh api user --jq '"You are @\(.login) (\(.name))."'
-
ディレクトリから、拡張機能をローカル拡張機能としてインストールします。
gh extension install .
-
拡張機能が機能することを確認します。
EXTENSION-NAME
は、お使いの拡張機能の名前に置き換えます。 たとえば、whoami
のようにします。gh EXTENSION-NAME
-
ディレクトリから、拡張機能を公開するリポジトリを作成します。
EXTENSION-NAME
は、お使いの拡張機能の名前に置き換えます。git init -b main git add . && git commit -m "initial commit" gh repo create gh-EXTENSION-NAME --source=. --public --push
-
必要に応じて、他のユーザーが拡張機能を検出できるように、リポジトリ トピック
gh-extension
を追加します。 これにより、拡張機能がgh-extension
トピック ページに表示されます。 リポジトリ トピックの追加方法について詳しくは、「トピックでリポジトリを分類する」をご覧ください。
解釈された GitHub CLI 拡張機能を記述するためのヒント
引数とフラグの処理
gh my-extension-name
コマンドに続くすべてのコマンド ライン引数は、拡張機能スクリプトに渡されます。 bash スクリプトでは、引数を$1
、$2
などで参照することができます。引数を使用して、ユーザーによる入力を取得したり、スクリプトの動作を変更したりできます。
たとえば、このスクリプトは複数のフラグを処理します。 スクリプトが -h
または --help
フラグで呼び出されると、スクリプトは実行を続行する代わりにヘルプ テキストを出力します。 スクリプトが --name
フラグで呼び出されると、スクリプトはフラグの次の値を name_arg
に設定します。 スクリプトが --verbose
フラグで呼び出されると、スクリプトは別のあいさつ文を出力します。
#!/usr/bin/env bash
set -e
verbose=""
name_arg=""
while [ $# -gt 0 ]; do
case "$1" in
--verbose)
verbose=1
;;
--name)
name_arg="$2"
shift
;;
-h|--help)
echo "Add help text here."
exit 0
;;
esac
shift
done
if [ -z "$name_arg" ]
then
echo "You haven't told us your name."
elif [ -z "$verbose" ]
then
echo "Hi $name_arg"
else
echo "Hello and welcome, $name_arg"
fi
非対話型モードでのコア コマンドの呼び出し
一部の GitHub CLI コア コマンドは、ユーザーに入力を求めます。 これらのコマンドを使用してスクリプトを作成する場合、プロンプトが望ましくないことがよくあります。 プロンプトが表示されないようにするには、引数を使用して必要な情報を明示的に指定します。
たとえば、プログラムで問題を作成するには、タイトルと本文を指定します。
gh issue create --title "My Title" --body "Issue description"
プログラムによるデータのフェッチ
多くのコア コマンドは、プログラムでデータをフェッチするための --json
フラグをサポートしています。 たとえば、pull request の数、タイトル、マージ可能性の状態を一覧表示する JSON オブジェクトを返すには、次のようにします。
gh pr list --json number,title,mergeStateStatus
GitHub から特定のデータをフェッチするコア コマンドがない場合は、gh api
コマンドを使用して GitHub API にアクセスできます。 たとえば、現在のユーザーに関する情報をフェッチするには、次のようにします。
gh api user
JSON データを出力するすべてのコマンドには、そのデータをスクリプトですぐに使用できるものにフィルター処理するオプションもあります。 たとえば、現在のユーザーの名前を取得するには、次のようにします。
gh api user --jq '.name'
詳細については、「gh help formatting
」を参照してください。
プリコンパイル済み拡張機能を手動で作成する
-
gh-EXTENSION-NAME
というローカル ディレクトリを作成し、拡張機能用に使用します。EXTENSION-NAME
は、お使いの拡張機能の名前に置き換えます。 たとえば、gh-whoami
のようにします。 -
作成したディレクトリにソース コードを追加します。 たとえば次のような点です。
package main import ( "github.com/cli/go-gh" "fmt" ) func main() { args := []string{"api", "user", "--jq", `"You are @\(.login) (\(.name))"` } stdOut, _, err := gh.Exec(args...) if err != nil { fmt.Println(err) return } fmt.Println(stdOut.String()) }
-
ディレクトリから、拡張機能をローカル拡張機能としてインストールします。
gh extension install .
-
コードをビルドします。 たとえば、Go を使用して、
YOUR-USERNAME
を GitHub ユーザー名に置き換えます。go mod init github.com/YOUR-USERNAME/gh-whoami go mod tidy go build
-
拡張機能が機能することを確認します。
EXTENSION-NAME
は、お使いの拡張機能の名前に置き換えます。 たとえば、whoami
のようにします。gh EXTENSION-NAME
-
ディレクトリから、拡張機能を公開するリポジトリを作成します。
EXTENSION-NAME
は、お使いの拡張機能の名前に置き換えます。Note
コンパイル ステップによって生成されたバイナリをバージョン コントロールにコミットしないように注意してください。
git init -b main echo "gh-EXTENSION-NAME" >> .gitignore git add main.go go.* .gitignore && git commit -m 'Initial commit' gh repo create "gh-EXTENSION-NAME"
-
プリコンパイル済み拡張機能を他のユーザーと共有するリリースを作成します。 サポートするプラットフォームごとにコンパイルし、各バイナリを資産としてリリースにアタッチします。 リリースにアタッチされるバイナリ実行可能ファイルは、名前付け規則に従い、OS-ARCHITECTURE[EXTENSION] のサフィックスを持つ必要があります。
たとえば、Windows 64 ビット用にコンパイルされた
whoami
という拡張機能の名前はgh-whoami-windows-amd64.exe
になり、Linux 32 ビット用にコンパイルされた同じ拡張機能の名前はgh-whoami-linux-386
になります。gh
で認識される OS とアーキテクチャの組み合わせの完全なリストについては、このソース コードを参照してください。Note
Windows で拡張機能を正常に実行するには、その資産ファイルの拡張子が
.exe
である必要があります。 他のオペレーティング システムでは拡張子は必要ありません。リリースはコマンド ラインから作成できます。 次に例を示します。
git tag v1.0.0 git push origin v1.0.0 GOOS=windows GOARCH=amd64 go build -o gh-EXTENSION-NAME-windows-amd64.exe GOOS=linux GOARCH=amd64 go build -o gh-EXTENSION-NAME-linux-amd64 GOOS=darwin GOARCH=amd64 go build -o gh-EXTENSION-NAME-darwin-amd64 gh release create v1.0.0 ./*amd64*
-
Optionally, to help other users discover your extension, add the repository topic
gh-extension
. This will make the extension appear on thegh-extension
topic page. For more information about how to add a repository topic, see "Classifying your repository with topics."
Tips for writing precompiled GitHub CLI extensions
Automating releases
Consider adding the gh-extension-precompile action to a workflow in your project. This action will automatically produce cross-compiled Go binaries for your extension and supplies build scaffolding for non-Go precompiled extensions.
Using GitHub CLI features from Go-based extensions
Consider using go-gh, a Go library that exposes pieces of gh
functionality for use in extensions.
Next steps
To see more examples of GitHub CLI extensions, look at repositories with the gh-extension
topic.