Сведения о расширениях 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 thegh-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.