Создание расширений GitHub CLI

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

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

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

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

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

С помощью аргумента --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 флаг для программного получения данных. Например, чтобы вернуть объект 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.

Создание предварительно скомпилированного расширения вручную

Создайте для расширения локальный каталог 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[.

Например, расширение с именем whoami, скомпилированное для 64-разрядной версии Windows, будет иметь имя gh-whoami-windows-amd64.exe, а то же расширение, скомпилированное для 32-разрядной версии Linux, будет иметь имя gh-whoami-linux-386. Полный список сочетаний ОС и архитектуры, распознаваемых gh, см. в этом исходном коде.

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 the gh-extension topic page. For more information about how to add a repository topic, see "Classifying your repository with topics."

Создание расширений GitHub CLI

В этой статье