Создание расширений 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, содержащий начальный код.

Настройте новое расширение с помощью подкоманды 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.
В созданном каталоге добавьте исполняемый файл с тем же именем, что и у каталога.

Примечание. Файл должен быть исполняемым. В 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 именем своего расширения.

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

Примечание. Чтобы расширение правильно выполнялось в 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

В этой статье