Skip to main content
We publish frequent updates to our documentation, and translation of this page may still be in progress. For the most current information, please visit the English documentation.
GitHub AE is currently under limited release.

Создание расширений 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. Следуйте выводимым инструкциям, чтобы завершить и при необходимости опубликовать расширение.

Создание предварительно скомпилированного расширения на Go с помощью gh extension create

С помощью аргумента --precompiled=go можно создать проект на основе Go для расширения, включая формирование шаблонов Go, формирование шаблонов рабочих процессов и начальный код.

  1. Настройте новое расширение с помощью подкоманды gh extension create. Замените EXTENSION-NAME именем своего расширения и укажите --precompiled=go.

    gh extension create --precompiled=go EXTENSION-NAME
  2. Следуйте выводимым инструкциям, чтобы завершить и при необходимости опубликовать расширение.

Создание предварительно скомпилированного расширения не на Go с помощью gh extension create

С помощью аргумента --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 main, git add file_name, а затем git 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 для доступа к API GitHub. Например, чтобы получить сведения о текущем пользователе, выполните следующую команду:

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. Создайте выпуск для предоставления доступа к предварительно скомпилированному расширению другим пользователям. Выполните компиляцию для каждой платформы, которая должна поддерживаться, прикрепив каждый двоичный файл к выпуску в качестве ресурса. Двоичные исполняемые файлы, прикрепляемые к выпускам, должны соответствовать соглашению об именовании и иметь суффикс ОС-АРХИТЕКТУРА[РАСШИРЕНИЕ].

    Например, расширение с именем whoami, скомпилированное для 64-разрядной версии Windows, будет иметь имя gh-whoami-windows-amd64.exe, а то же расширение, скомпилированное для 32-разрядной версии Linux, будет иметь имя 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*
    
    
  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. 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.