# GitHub CLI 拡張機能の作成 GitHub CLI のカスタム拡張機能を作成して、新しい GitHub CLI コマンドを他のユーザーと共有する方法について学びます。 ## GitHub CLI 拡張機能について GitHub CLI 拡張機能は、だれでも作成して使用できる、カスタム GitHub CLI コマンドです。GitHub CLI 拡張機能の使用方法の詳細については、「[GitHub CLI 拡張機能の使用](/ja/github-cli/github-cli/using-github-cli-extensions)を参照してください。 作成する拡張機能ごとにリポジトリが必要です。 リポジトリ名は `gh-` で始まる必要があります。 リポジトリ名の残りの部分は拡張機能の名前です。 リポジトリのルートには、リポジトリと同じ名前の実行可能ファイル、またはリリースにアタッチされたプリコンパイル済みバイナリ実行可能ファイルのセットが必要です。 > \[!NOTE] > 実行可能スクリプトに依存する場合は、bash スクリプトを使用することをお勧めします。bash は広く利用できるインタープリターであるためです。 bash 以外のスクリプトを使用できますが、拡張機能を使用するには、ユーザーに必要なインタープリターがインストールされている必要があります。 インタープリターがインストールされているユーザーに依存しない場合は、プリコンパイル済み拡張機能を検討してください。 ## ``` `gh extension create` で解釈される拡張機能を作成する ``` > \[!NOTE] > 引数なしで `gh extension create` を実行すると、対話型ウィザードが開始されます。 ``` `gh extension create` コマンドを使用して、いくつかのスターター コードを含む bash スクリプトを含む拡張機能のprojectを作成できます。 ``` 1\. `gh extension create` サブコマンドを使用して、新しい拡張機能を設定します。 `EXTENSION-NAME` は、お使いの拡張機能の名前に置き換えます。 ```` ```shell gh extension create EXTENSION-NAME ``` ```` 1. 表示された指示に従って、拡張機能を最終処理し、必要に応じて公開します。 ## ``` `gh extension create` を使用して Go でプリコンパイル済み拡張機能を作成する `--precompiled=go` 引数を使用して、Go スキャフォールディング、ワークフロー スキャフォールディング、スターター コードなど、拡張機能の Go ベースのprojectを作成できます。 ``` 1\. `gh extension create` サブコマンドを使用して、新しい拡張機能を設定します。 `EXTENSION-NAME` は、お使いの拡張機能の名前に置き換えて、`--precompiled=go` を指定します。 ```` ```shell gh extension create --precompiled=go EXTENSION-NAME ``` ```` 1. 表示された指示に従って、拡張機能を最終処理し、必要に応じて公開します。 ## ``` `gh extension create` を使用して Go 以外のプリコンパイル済み拡張機能を作成する `--precompiled=other` 引数を使用して、Go 以外のプリコンパイル済み拡張機能のproject (ワークフロー スキャフォールディングを含む) を作成できます。 ``` 1\. `gh extension create` サブコマンドを使用して、新しい拡張機能を設定します。 `EXTENSION-NAME` は、お使いの拡張機能の名前に置き換えて、`--precompiled=other` を指定します。 ```` ```shell gh extension create --precompiled=other EXTENSION-NAME ``` ```` 1. 選択したコンパイル済み言語に拡張機能の初期コードをいくつか追加します。 2. 拡張機能を自動的にビルドできるように、`script/build.sh` に拡張機能をビルドするコードを入力します。 3. 表示された指示に従って、拡張機能を最終処理し、必要に応じて公開します。 ## 解釈される拡張機能を手動で作成する 1. ``` `gh-EXTENSION-NAME` というローカル ディレクトリを作成し、拡張機能用に使用します。 `EXTENSION-NAME` は、お使いの拡張機能の名前に置き換えます。 たとえば、`gh-whoami` のようにします。 ``` 2. 作成したディレクトリに、ディレクトリと同じ名前の実行可能ファイルを追加します。 > \[!NOTE] > ファイルが実行可能であることを確認します。 UNIX では、コマンド ラインで `chmod +x file_name` を実行して、`file_name` を実行可能にできます。 Windows では、`git init -b main`、`git add file_name`、そして `git update-index --chmod=+x file_name` を実行できます。 3. 実行可能ファイルにスクリプトを記述します。 たとえば次のような点です。 ```bash #!/usr/bin/env bash set -e exec gh api user --jq '"You are @\(.login) (\(.name))."' ``` 4. ディレクトリから、拡張機能をローカル拡張機能としてインストールします。 ```shell gh extension install . ``` 5. 拡張機能が機能することを確認します。 `EXTENSION-NAME` は、お使いの拡張機能の名前に置き換えます。 たとえば、`whoami` のようにします。 ```shell gh EXTENSION-NAME ``` 6. ディレクトリから、拡張機能を公開するリポジトリを作成します。 `EXTENSION-NAME` は、お使いの拡張機能の名前に置き換えます。 ```shell git init -b main git add . && git commit -m "initial commit" gh repo create gh-EXTENSION-NAME --source=. --public --push ``` 7. 必要に応じて、他のユーザーが拡張機能を検出できるように、リポジトリ トピック `gh-extension` を追加します。 これにより、拡張機能が [`gh-extension` トピック ページ](https://github.com/topics/gh-extension)に表示されます。 リポジトリ トピックの追加方法の詳細については、「[トピックでリポジトリを分類する](/ja/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics)」を参照してください。 ## 解釈された GitHub CLI 拡張機能を記述するためのヒント ### 引数とフラグの処理 ``` `gh my-extension-name` コマンドに続くすべてのコマンド ライン引数は、拡張機能スクリプトに渡されます。 bash スクリプトでは、引数を`$1`、`$2` などで参照することができます。引数を使用して、ユーザーによる入力を取得したり、スクリプトの動作を変更したりできます。 ``` たとえば、このスクリプトは複数のフラグを処理します。 スクリプトが `-h` または `--help` フラグで呼び出されると、スクリプトは実行を続行する代わりにヘルプ テキストを出力します。 スクリプトが `--name` フラグで呼び出されると、スクリプトはフラグの次の値を `name_arg` に設定します。 スクリプトが `--verbose` フラグで呼び出されると、スクリプトは別のあいさつ文を出力します。 ```bash #!/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 コア コマンドは、ユーザーに入力を求めます。 これらのコマンドを使用してスクリプトを作成する場合、プロンプトが望ましくないことがよくあります。 プロンプトが表示されないようにするには、引数を使用して必要な情報を明示的に指定します。 たとえば、プログラムで問題を作成するには、タイトルと本文を指定します。 ```shell gh issue create --title "My Title" --body "Issue description" ``` ### プログラムによるデータの取得 多くのコア コマンドは、プログラムでデータをフェッチするための `--json` フラグをサポートしています。 たとえば、pull request の数、タイトル、マージ可能性の状態を一覧表示する JSON オブジェクトを返すには、次のようにします。 ```shell gh pr list --json number,title,mergeStateStatus ``` GitHubから特定のデータをフェッチするコア コマンドがない場合は、[`gh api`](https://cli.github.com/manual/gh_api) コマンドを使用して、GitHub API をaccessできます。 たとえば、現在のユーザーに関する情報をフェッチするには、次のようにします。 ```shell gh api user ``` JSON データを出力するすべてのコマンドには、そのデータをスクリプトですぐに使用できるものにフィルター処理するオプションもあります。 たとえば、現在のユーザーの名前を取得するには、次のようにします。 ```shell gh api user --jq '.name' ``` 詳細については、「[`gh help formatting`](https://cli.github.com/manual/gh_help_formatting)を参照してください。 ## プリコンパイル済み拡張機能を手動で作成する 1. ``` `gh-EXTENSION-NAME` というローカル ディレクトリを作成し、拡張機能用に使用します。 `EXTENSION-NAME` は、お使いの拡張機能の名前に置き換えます。 たとえば、`gh-whoami` のようにします。 ``` 2. 作成したディレクトリにソース コードを追加します。 たとえば次のような点です。 ```golang 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()) } ``` 3. ディレクトリから、拡張機能をローカル拡張機能としてインストールします。 ```shell gh extension install . ``` 4. コードをビルドします。 たとえば、Go では、`YOUR-USERNAME`をGitHubユーザー名に置き換えます。 ```shell go mod init github.com/YOUR-USERNAME/gh-whoami go mod tidy go build ``` 5. 拡張機能が機能することを確認します。 `EXTENSION-NAME` は、お使いの拡張機能の名前に置き換えます。 たとえば、`whoami` のようにします。 ```shell gh EXTENSION-NAME ``` 6. ディレクトリから、拡張機能を公開するリポジトリを作成します。 `EXTENSION-NAME` は、お使いの拡張機能の名前に置き換えます。 > \[!NOTE] > コンパイル ステップによって生成されたバイナリをバージョン コントロールにコミットしないように注意してください。 ```shell 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" ``` 7. プリコンパイル済み拡張機能を他のユーザーと共有するリリースを作成します。 サポートするプラットフォームごとにコンパイルし、各バイナリを資産としてリリースにアタッチします。 リリースにアタッチされるバイナリ実行可能ファイルは、名前付け規則に従い、OS-ARCHITECTURE\[EXTENSION] のサフィックスを持つ必要があります。 たとえば、Windows 64 ビット用にコンパイルされた `whoami` という拡張機能の名前は `gh-whoami-windows-amd64.exe` になり、Linux 32 ビット用にコンパイルされた同じ拡張機能の名前は `gh-whoami-linux-386` になります。 `gh` によって認識される OS とアーキテクチャの組み合わせの完全な一覧については、[このソース コード](https://github.com/cli/cli/blob/14f704fd0da58cc01413ee4ba16f13f27e33d15e/pkg/cmd/extension/manager.go#L696)を参照してください。 > \[!NOTE] > Windows で拡張機能を正常に実行するには、その資産ファイルの拡張子が `.exe` である必要があります。 他のオペレーティング システムでは拡張子は必要ありません。 リリースはコマンド ラインから作成できます。 たとえば次のような点です。 ```shell 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* ``` 8. Optionally, to help other users discover your extension, add the repository topic `gh-extension`. This will make the extension appear on the [`gh-extension` topic page](https://github.com/topics/gh-extension). For more information about how to add a repository topic, see [Classifying your repository with topics](/ja/github/administering-a-repository/managing-repository-settings/classifying-your-repository-with-topics). ## Tips for writing precompiled GitHub CLI extensions ### Automating releases Consider adding the [gh-extension-precompile](https://github.com/cli/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](https://github.com/cli/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](https://github.com/topics/gh-extension).