# GitHub CLI (gh)

_Инструменты · GitLab Knowledge Base_

**TL;DR:** Официальный CLI от GitHub. Работает с GitHub-объектами (PR,
issues, Actions, releases, releases), которых в чистом Git нет.
Не замена git, а дополнение второго слоя. Установка через
brew/apt/winget, авторизация через `gh auth login`.


`gh` - официальный command-line tool от GitHub. В отличие от `git`,
который работает с локальным `.git/` и пушит коммиты, `gh` ходит
в GitHub API: создаёт PR, листает issues, просматривает Actions
runs, скачивает релизы. Эти вещи живут в базе GitHub, не в
объектах Git.

## Установка

```bash
# macOS
brew install gh

# Ubuntu/Debian
sudo apt install gh

# Windows
winget install GitHub.cli
scoop install gh

# проверка
gh --version
```

Полный список инсталлеров - на `cli.github.com`.

## Авторизация

```bash
gh auth login
```

Команда задаёт несколько вопросов (GitHub.com/Enterprise, HTTPS/SSH,
через браузер или с токеном) и сохраняет OAuth-токен в keychain
ОС. После этого:

```bash
gh auth status      # под какой учёткой, какие scopes
gh auth switch      # переключить между несколькими учётками
gh auth logout      # отозвать
```

## Главные команды

```bash
# репозитории
gh repo clone owner/repo
gh repo fork owner/repo --clone   # форк + клон + remote setup
gh repo create my-project --public --source=. --push

# pull requests
gh pr create -t "fix login" -b "Fixes #142"
gh pr list --author "@me"
gh pr view 123
gh pr checkout 123             # достаёт ветку любого PR локально
gh pr review --approve
gh pr merge --squash --delete-branch
gh pr checks --watch           # следить за CI в реальном времени

# issues
gh issue create -t "Bug: ..." -b "..."
gh issue list --label bug

# actions
gh workflow run ci.yml
gh run list --workflow ci.yml
gh run view 12345 --log
gh run rerun --failed
```

## JSON-вывод для скриптов

Почти любая команда принимает `--json` с указанием полей:

```bash
gh pr list --json number,title,author \
  | jq -r '.[] | "\(.number) - \(.title) by \(.author.login)"'
```

Список валидных полей - `--json` без аргументов покажет ошибку с
ним. Это надёжный способ узнать, что доступно.

## Алиасы

```bash
gh alias set co 'pr checkout'
gh alias set prs 'pr list --author "@me"'
```

Алиасы хранятся в `~/.config/gh/config.yml`. Принимают `$1`, `$2`
для подстановки аргументов.

## Escape hatch: gh api

Когда нативной команды нет - сырой доступ к REST/GraphQL:

```bash
gh api repos/cli/cli/contributors --jq '.[].login'
gh api graphql -f query='query { viewer { login } }'
```

gh берёт на себя авторизацию, пагинацию, ретраи.

## Когда gh быстрее браузера

- Создание PR из текущей ветки (`gh pr create`).
- Чекаут чужого PR для тестирования (`gh pr checkout`).
- Просмотр CI-логов с grep.
- Batch-операции и скрипты.
- Создание issue без отвлечения от терминала.

## Когда браузер удобнее

- Inline code review (тянуть мышью по строкам).
- Длинные обсуждения с несколькими участниками.
- Большие diff'ы с многими файлами.
- Repository settings, organization management.

Оба инструмента сосуществуют. Терминал для скорости, браузер
для визуальной проработки. Подробности - в главе 16.


## Команды

```bash
gh auth login
```
Авторизоваться, настроить git credential helper

```bash
gh pr create -t 'title' -b 'body'
```
Создать PR из текущей ветки

```bash
gh pr checkout 123
```
Локально достать ветку PR #123, включая PR из чужих fork'ов

```bash
gh pr merge --auto --squash
```
Включить auto-merge: сольёт когда все checks зелёные

```bash
gh run view --log | grep -i error
```
Скачать логи последнего CI-run и поискать ошибки


## См. также

- [Pull Request (PR)](/courses/git/kb/pull-request.md)
- [Code review](/courses/git/kb/code-review.md)
- [Draft pull request](/courses/git/kb/draft-pr.md)