Skip to main content

此版本的 GitHub Enterprise 已停止服务 2022-06-03. 即使针对重大安全问题,也不会发布补丁。 要获得更好的性能、改进的安全性和新功能,请升级到 GitHub Enterprise 的最新版本。 如需升级方面的帮助,请联系 GitHub Enterprise 支持

创建 GitHub CLI 扩展

了解如何通过为 GitHub CLI 创建自定义扩展程序与其他用户共享新的 GitHub CLI 命令。

关于 GitHub CLI 扩展

GitHub CLI 扩展是任何人都可以创建和使用的自定义 GitHub CLI 命令。 有关如何使用 GitHub CLI 扩展的详细信息,请参阅“使用 GitHub CLI 扩展”。

对于您创建的每个扩展,都需要一个存储库。 存储库名称必须以 gh-开头。 存储库名称的其余部分是扩展的名称。 存储库的� �目录下必须有一个与存储库同名的可执行文件,或者附� 到发行版的一组预编译二进制可执行文件。

注意:当依赖于可执行脚本时,我们建议使用 bash 脚本,� 为 bash 是一个广泛使用的解译程序。 您可以使用非 bash 脚本,但用户必须安装必要的解译程序才能使用扩展。 如果您不希望依赖安装了解译程序的用户,请考虑使用预编译扩展。

使用 gh extension create 创建解译的扩展

注意:运行不带参数的 gh extension create 将启动交互式向导。

可以使用 gh extension create 命令为您的扩展创建一个项目,包括包含一些起始代� �的 bash 脚本。

  1. 使用 gh extension create 子命令设置新的扩展。 将 EXTENSION-NAME 替换为扩展的名称。

    gh extension create EXTENSION-NAME
  2. 按照打印的说明完成扩展并选择性地发布扩展。

使用 gh extension create创建预编译的扩展

可以使用 --precompiled=go 参数为扩展创建基于 Go 的项目,包括 Go 基架、工作流程基架和起始代� �。

  1. 使用 gh extension create 子命令设置新的扩展。 将 EXTENSION-NAME 替换为扩展的名称,并指定 --precompiled=go

    gh extension create --precompiled=go EXTENSION-NAME
  2. 按照打印的说明完成扩展并选择性地发布扩展。

使用 gh extension create创建非 Go 预编译的扩展

可以使用 --precompiled=other 参数为非 Go 预编译扩展(包括工作流程基架)创建项目。

  1. 使用 gh extension create 子命令设置新的扩展。 将 EXTENSION-NAME 替换为扩展名,并指定 --precompiled=other

    gh extension create --precompiled=other EXTENSION-NAME
  2. 使用所选的编译语言为扩展添� 一些初始代� �。

  3. script/build.sh 中填写代� �以生成扩展,以确保可以自动生成扩展。

  4. 按照打印的说明完成扩展并选择性地发布扩展。

手动创建解译的扩展

  1. 为扩展创建一个名为 gh-EXTENSION-NAME 的本地目录。 将 EXTENSION-NAME 替换为扩展的名称。 例如,gh-whoami

  2. 在您创建的目录中,添� 与该目录同名的可执行文件。

    注意: 请确保您的文件是可执行的。 在 Unix上,您可以在命令行中执行 chmod +x file_name ,以使 file_name 可执行。 在 Windows上,您可以依次运行 git init -b maingit add file_namegit update-index --chmod=+x file_name

  3. 在可执行文件中编写脚本。 例如:

    #!/usr/bin/env bash
    set -e
    exec gh api user --jq '"You are @\(.login) (\(.name))."'
    
  4. 从目录中,将扩展安装为本地扩展。

    gh extension install .
  5. 验证您的扩展是否正常工作。 将 EXTENSION-NAME 替换为扩展的名称。 例如 whoami

    gh EXTENSION-NAME
  6. 从目录中,创建一个存储库以发布扩展。 将 EXTENSION-NAME 替换为扩展的名称。

    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 主题页面上。 有关如何添� 存储库主题的更多信息,请参阅“使用主题对存储库进行分类”。

编写解译型 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

手动创建预编译的扩展

  1. 为扩展创建一个名为 gh-EXTENSION-NAME 的本地目录。 将 EXTENSION-NAME 替换为扩展的名称。 例如,gh-whoami

  2. 在您创建的目录中,添� 一些源代� �。 例如:

    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. 从目录中,将扩展安装为本地扩展。

    gh extension install .
  4. 生成代� �。 例如,使用 Go,将 YOUR-USERNAME 替换为您的 GitHub 用户名:

    go mod init github.com/YOUR-USERNAME/gh-whoami
    go mod tidy
    go build
  5. 验证您的扩展是否正常工作。 将 EXTENSION-NAME 替换为扩展的名称。 例如 whoami

    gh EXTENSION-NAME
  6. 从目录中,创建一个存储库以发布扩展。 将 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"
  7. 创建版本以与他人共享预编译的扩展。 针对要支持的每个平台进行编译,将每个二进制文件作为资产附� 到发行版。 附� 到发行版的二进制可执行文件必须遵循命名约定,并且具有 OS-ARCHITECTURE[EXTENSION] 的后缀。

    例如,为 Windows 64 位编译的名为 whoami 的扩展将具有名称 gh-whoami-windows-amd64.exe,而为 Linux 32 位编译的同一扩展具有名称 gh-whoami-linux-386。 要查看 gh 识别的操作系统和架构的详尽列表,请参阅此源代� �

    注意:要使扩展在 Windows 上正常运行,其资产文件必须具有 .exe 扩展名。 其他操作系统不需要扩展。

    可以从命令行创建版本。 例如:

  8. (可选)为了帮助其他用户发现您的扩展,请添� 存储库主题 gh-extension。 这将使扩展显示在 gh-extension 主题页面上。 有关如何添� 存储库主题的更多信息,请参阅“使用主题对存储库进行分类”。

编写预编译 GitHub CLI 扩展的提示

自动化发布

考虑将 gh-extension-precompiled 操作添� 到项目中的工作流程。 此操作将自动为您的扩展生成交叉编译的 Go 二进制文件,并为非 Go 预编译扩展提供构建基架。

使用基于 Go 的扩展中的 GitHub CLI 功能

考虑使用 go-gh,这是一个公开 gh 功能的 Go 库,用于扩展。

后续步骤

要查看 GitHub CLI 扩展的更多示例,请查看 具有 gh-extension 主题的存储库