创建 GitHub CLI 扩展

关于 GitHub CLI 扩展

GitHub CLI 扩展是任何人都可以创建和使用的自定义 GitHub CLI 命令。有关如何使用 GitHub CLI 扩展的更多信息，请参阅使用 GitHub CLI 扩展。

每个要创建的扩展都需要一个代码仓库。仓库名称必须以 gh- 开头。其余部分即为扩展的名称。仓库的根目录必须有一个与仓库同名的可执行文件，或是一组随发布（release）附带的预编译二进制可执行文件。

注意

在依赖可执行脚本时，建议使用 bash 脚本，因为 bash 是一种广泛可用的解释器。您可以使用非 bash 脚本，但用户必须已安装相应的解释器才能使用该扩展。如果您希望避免依赖用户安装解释器，请考虑使用预编译扩展。

使用 `gh extension create` 创建解释型扩展

注意

在不带参数运行 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。
在您创建的目录中，添加一个与目录同名的可执行文件。

注意

确保您的文件具有可执行权限。在 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 标志，可用于以编程方式获取数据。例如，返回一个 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 替换为您的扩展名称。

注意

请注意不要将编译生成的二进制文件提交到版本控制。
```
 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"
```
创建一个发布（release）以与他人共享您的预编译扩展。针对每个想要支持的平台进行编译，并将每个二进制文件作为资产附加到发布中。附加到发布的二进制可执行文件必须遵循命名约定，后缀为 OS-ARCHITECTURE[EXTENSION]。

例如，名为 whoami 的扩展，如果为 Windows 64 位编译，其名称为 gh-whoami-windows-amd64.exe；而同一扩展如果为 Linux 32 位编译，其名称为 gh-whoami-linux-386。若要查看 gh 支持的所有操作系统和架构组合的完整列表，请参阅此源代码。

注意

要使扩展在 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*
```
可选地，为了帮助其他用户发现您的扩展，请添加仓库话题 gh-extension。这将使扩展出现在 gh-extension 话题页面。有关如何添加仓库话题的详细信息，请参阅使用话题对仓库进行分类。

本文内容