# Создание расширений GitHub CLI Узнайте, как использовать новые команды GitHub CLI совместно с другими пользователями, создавая пользовательские расширения для GitHub CLI. ## Сведения о расширениях GitHub CLI Расширения GitHub CLI — это пользовательские команды GitHub CLI, которые может создавать и применять любой пользователь. Для получения дополнительной информации о том, как использовать расширения GitHub CLI, см. [Использование расширений GitHub CLI](/ru/github-cli/github-cli/using-github-cli-extensions). Вам потребуется репозиторий для каждого создаваемого расширения. Имя репозитория должно начинаться с `gh-`. Остальная часть имени репозитория — это имя расширения. В корне репозитория должен быть исполняемый файл с тем же именем, что и у репозитория, либо к выпуску должен быть прикреплен набор предварительно скомпилированных двоичных исполняемых файлов. > \[!NOTE] > При использовании исполняемого скрипта рекомендуется использовать скрипт bash, так как bash является широко доступным интерпретатором. Вы можете использовать скрипты, отличные от bash, но для использования расширения у пользователя должен быть установлен необходимый интерпретатор. Чтобы не зависеть от наличия интерпретатора у пользователя, можно предварительно скомпилировать расширение. ## Создание интерпретируемого расширения с помощью `gh extension create` > \[!NOTE] > Выполнение `gh extension create` без аргументов запустит интерактивный мастер. Вы можете использовать команду `gh extension create` для создания project для расширения, включая bash-скрипт с некоторым стартовым кодом. 1. Настройте новое расширение с помощью подкоманды `gh extension create`. Замените `EXTENSION-NAME` именем своего расширения. ```shell gh extension create EXTENSION-NAME ``` 2. Следуйте выводимым инструкциям, чтобы завершить и при необходимости опубликовать расширение. ## Создание предварительно скомпилированного расширения на Go с помощью `gh extension create` Вы можете использовать аргумент `--precompiled=go`, чтобы создать project на базе Go, включая строительные леса, рабочие процессы и стартовый код. 1. Настройте новое расширение с помощью подкоманды `gh extension create`. Замените `EXTENSION-NAME` именем своего расширения и укажите `--precompiled=go`. ```shell gh extension create --precompiled=go EXTENSION-NAME ``` 2. Следуйте выводимым инструкциям, чтобы завершить и при необходимости опубликовать расширение. ## Создание предварительно скомпилированного расширения не на Go с помощью `gh extension create` Вы можете использовать аргумент `--precompiled=other`, чтобы создать project для вашего не-Go предварительно скомпилированного расширения, включая подкрепление рабочих процессов. 1. Настройте новое расширение с помощью подкоманды `gh extension create`. Замените `EXTENSION-NAME` именем своего расширения и укажите `--precompiled=other`. ```shell gh extension create --precompiled=other EXTENSION-NAME ``` 2. Добавьте исходный код расширения на предпочтительном компилируемом языке. 3. Заполните файл `script/build.sh` кодом так, чтобы сборка расширения могла быть выполнена автоматически. 4. Следуйте выводимым инструкциям, чтобы завершить и при необходимости опубликовать расширение. ## Создание интерпретируемого расширения вручную 1. Создайте для расширения локальный каталог `gh-EXTENSION-NAME`. Замените `EXTENSION-NAME` именем своего расширения. Например, `gh-whoami`. 2. В созданном каталоге добавьте исполняемый файл с тем же именем, что и у каталога. > \[!NOTE] > Убедитесь, что файл является исполняемым. В Unix можно выполнить в командной строке команду `chmod +x file_name`, чтобы сделать файл `file_name` исполняемым. В Windows можно выполнить `git init -b main`, `git add file_name`, а затем `git update-index --chmod=+x file_name`. 3. Напишите скрипт в исполняемом файле. Например: ```bash #!/usr/bin/env bash set -e exec gh api user --jq '"You are @\(.login) (\(.name))."' ``` 4. Из каталога установите расширение в качестве локального. ```shell gh extension install . ``` 5. Убедитесь в том, что расширение работает. Замените `EXTENSION-NAME` именем своего расширения. Например, `whoami`. ```shell gh EXTENSION-NAME ``` 6. Создайте репозиторий из каталога для публикации расширения. Замените `EXTENSION-NAME` именем своего расширения. ```shell 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`](https://github.com/topics/gh-extension). Дополнительные сведения о добавлении раздела репозитория см. в разделе [Классификация репозитория с помощью тем](/ru/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics). ## Советы по написанию интерпретируемых расширений GitHub CLI ### Работа с аргументами и флагами Все аргументы командной строки после команды `gh my-extension-name` будут передаваться в скрипт расширения. В скрипте bash можно ссылаться на аргументы с помощью `$1`, `$2` и т. д. С помощью аргументов можно принимать вводимые пользователем данные или изменять выполнение скрипта. Например, приведенный ниже скрипт обрабатывает несколько флагов. При вызове скрипта с флагом `-h` или `--help` он выводит текст справки вместо продолжения выполнения. При вызове скрипта с флагом `--name` он задает следующее после флага значение равным `name_arg`. При вызове скрипта с флагом `--verbose` он выводит другое приветствие. ```bash #!/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 запрашивают у пользователя ввод данных. При написании скриптов с помощью этих команд запросы часто нежелательны. Чтобы избежать их вывода, укажите необходимые сведения явным образом с помощью аргументов. Например, чтобы создать проблему программным способом, укажите заголовок и текст: ```shell gh issue create --title "My Title" --body "Issue description" ``` ### Извлечение данных программным способом Многие основные команды поддерживают `--json` флаг для программного получения данных. Например, чтобы вернуть объект JSON со списком номеров, заголовков и состояний возможности слияния запросов на вытягивание, выполните следующую команду: ```shell gh pr list --json number,title,mergeStateStatus ``` Если нет основной команды для извлечения конкретных данных из GitHub, вы можете использовать команду [`gh api`](https://cli.github.com/manual/gh_api) для access GitHub API. Например, чтобы получить сведения о текущем пользователе, выполните следующую команду: ```shell gh api user ``` Все команды, которые выводят данные JSON, также имеют параметры для фильтрации данных с целью их немедленного использования скриптами. Например, чтобы получить имя текущего пользователя, выполните следующую команду: ```shell gh api user --jq '.name' ``` Для получения дополнительной информации см. [`gh help formatting`](https://cli.github.com/manual/gh_help_formatting). ## Создание предварительно скомпилированного расширения вручную 1. Создайте для расширения локальный каталог `gh-EXTENSION-NAME`. Замените `EXTENSION-NAME` именем своего расширения. Например, `gh-whoami`. 2. В созданном каталоге добавьте исходный код. Например: ```golang 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. Из каталога установите расширение в качестве локального. ```shell gh extension install . ``` 4. Выполните сборку кода. Например, при Go заменить `YOUR-USERNAME` на ваш GitHub ник: ```shell go mod init github.com/YOUR-USERNAME/gh-whoami go mod tidy go build ``` 5. Убедитесь в том, что расширение работает. Замените `EXTENSION-NAME` именем своего расширения. Например, `whoami`. ```shell gh EXTENSION-NAME ``` 6. Создайте репозиторий из каталога для публикации расширения. Замените `EXTENSION-NAME` именем своего расширения. > \[!NOTE] > Будьте осторожны, чтобы не зафиксировать двоичный файл, созданный на шаге компиляции, в управление версиями. ```shell 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]. Например, расширение с именем `whoami`, скомпилированное для 64-разрядной версии Windows, будет иметь имя `gh-whoami-windows-amd64.exe`, а то же расширение, скомпилированное для 32-разрядной версии Linux, будет иметь имя `gh-whoami-linux-386`. Чтобы увидеть исчерпывающий список комбинаций ОС и архитектур, распознанных `gh`, см. [этот исходный код](https://github.com/cli/cli/blob/14f704fd0da58cc01413ee4ba16f13f27e33d15e/pkg/cmd/extension/manager.go#L696). > \[!NOTE] > Чтобы расширение выполнялось правильно в Windows, его файл ресурса должен иметь `.exe` расширение. Для других операционных систем расширение не требуется. Выпуски можно создавать из командной строки. Например: ```shell 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](https://github.com/topics/gh-extension). For more information about how to add a repository topic, see [Classifying your repository with topics](/ru/github/administering-a-repository/managing-repository-settings/classifying-your-repository-with-topics). ## Tips for writing precompiled GitHub CLI extensions ### Automating releases Consider adding the [gh-extension-precompile](https://github.com/cli/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](https://github.com/cli/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](https://github.com/topics/gh-extension).