GitHub CLI: работа с GitHub без браузера

Самая частая путаница на старте: «зачем мне gh, если у меня уже есть git». Ответ -они про разное.

git работает с локальным .git/ и удалёнными bare-репами через push/fetch. Он ничего не знает про pull request, issue, Actions -этих понятий в Git как протоколе не существует. Они живут в базе GitHub.

gh работает с GitHub API. Через REST/GraphQL он создаёт PR, листает issues, просматривает Actions runs, скачивает релизы. В Git как таковом этого нет.

Простой тест на путаницу: вопрос про коммиты, ветки, diff, merge, rebase -это git. Вопрос про PR, issue, review, label, milestone, Actions, release -это gh. Когда вопрос смешанный (например, «открыть PR из текущей ветки»), нужны оба: git push пушит ветку, gh pr create открывает PR на ней.

Иерархия:

твой код в файлах

      ↓ git add, git commit

твоя локальная .git/

      ↓ git push

bare-репо на GitHub (origin)

      ↓ gh pr create

pull request в базе GitHub

Каждая стрелка -свой инструмент. Их не имеет смысла объединять в один: они про разные слои. gh намеренно не дублирует возможности git (push, clone, fetch).

Установка зависит от системы:

# macOS

brew install gh

# Ubuntu/Debian

sudo apt install gh   # на свежих, иначе добавить репо cli.github.com

# Windows

winget install GitHub.cli

# или

scoop install gh

# проверка

gh --version

Полный список -в cli.github.com. На большинстве систем процесс одной команды.

Дальше -авторизация:

gh auth login

Команда задаёт несколько вопросов:

1. GitHub.com или GitHub Enterprise Server? Обычно GitHub.com.
2. Protocol для git: HTTPS или SSH? Если уже настроен ssh-keys-git, выбирай SSH -gh будет работать согласованно с твоим git. Если SSH ещё нет, HTTPS проще (gh сам настроит credential helper).
3. Authenticate Git с GitHub credentials? Да. gh настроит git credential helper, чтобы git push через HTTPS не просил пароль каждый раз.
4. How would you like to authenticate? Login with a web browser -удобнее всего. Откроется браузер, gh покажет код, ты подтвердишь в браузере, токен сохранится локально.

После этого:

gh auth status

Покажет, под какой учёткой ты, с какими scopes. Полезно, когда пытаешься сделать что-то и получаешь permission denied -проверь сначала status.

Токен gh хранит в:

• macOS: Keychain.
• Linux: secret-service (gnome-keyring/kwallet) или ~/.config/gh/hosts.yml в чистом виде, если keyring нет.
• Windows: Credential Manager.

Это не personal access token, который ты бы создал вручную в Settings. Это отдельный OAuth-токен, выданный gh-приложению. Если хочешь отозвать -gh auth logout, или вручную через GitHub Settings -> Applications -> Authorized OAuth Apps.

Несколько аккаунтов одновременно: gh auth login ещё раз с другим аккаунтом, потом gh auth switch для переключения. На работе это часто бывает -личный аккаунт и рабочий.

Базовые операции с репозиториями. Что добавляет gh поверх обычного git:

gh repo clone

gh repo clone cli/cli

Эквивалент обычного git clone, но не нужно помнить URL - достаточно owner/repo. Какой URL подставится (SSH-style git@github.com:... или HTTPS-style https://github.com/...), зависит от gh config get git_protocol; выбор делается во время gh auth login или вручную через gh config set git_protocol ssh|https. Если авторизация по HTTPS, gh настраивает credentials автоматически без ручного credential helper'а.

gh repo fork

gh repo fork acme/web

Делает fork на GitHub и добавляет два remote локально:

origin    git@github.com:me/web.git    (твой fork)

upstream  git@github.com:acme/web.git  (оригинал)

Это то, что в upstream-vs-origin делаешь вручную из трёх команд:

# вручную:

gh api repos/acme/web/forks -X POST

git clone git@github.com:me/web.git

cd web

git remote add upstream git@github.com:acme/web.git

# эквивалент через gh:

gh repo fork acme/web --clone

Полезные флаги:

• --clone -сразу склонировать локально.
• --remote -добавить fork как remote origin в существующий clone (когда ты уже работал с upstream, а потом решил сделать fork).

gh repo create

# создать новый репо из текущей директории

gh repo create my-project --public --source=. --push

# или интерактивно

gh repo create

Делает: создаёт репо на GitHub, добавляет origin, делает первый push. В одной команде то, что обычно делаешь в три шага.

gh repo view

gh repo view acme/web

gh repo view acme/web --web    # открыть в браузере

Показывает README и базовую инфу прямо в терминале. --web -shortcut для открытия в браузере, удобно когда быстро надо что-то посмотреть.

Pull request -центральный объект GitHub-workflow, и gh pr - главная подкоманда gh.

Создать PR

# из текущей ветки в дефолтную ветку (обычно main)

gh pr create

# с явным заголовком и описанием

gh pr create -t "fix login crash" -b "Fixes #142"

# draft PR

gh pr create --draft

# сразу укажи reviewer'ов и labels

gh pr create -r alice,bob -l bug,backend

Без флагов команда задаёт вопросы интерактивно. С флагами - одна команда без отвлечения. Описание поддерживает markdown.

Если есть .github/PULL_REQUEST_TEMPLATE.md в репо, gh подставит его как стартовое описание. Откроется в $EDITOR, редактируешь, сохраняешь -PR создан.

Список и поиск

gh pr list                          # открытые PR в текущем репо

gh pr list --state closed           # закрытые

gh pr list --author "@me"           # мои PR

gh pr list --label bug              # с лейблом bug

gh pr list --search "is:open draft" # синтаксис поиска как в UI

Посмотреть PR в терминале

gh pr view 123                       # обзор + комментарии

gh pr view 123 --comments            # развёрнуто

gh pr view 123 --web                 # открыть в браузере

gh pr diff 123                       # diff всего PR

gh pr view отлично работает на маленьких PR. На больших diff'ах удобнее --web: терминал не покажет inline-обсуждения по строкам так же удобно, как UI.

Скачать PR локально для review

Главная команда, ради которой стоит ставить gh:

gh pr checkout 123

Что делает:

1. Находит ветку PR (включая ветки из чужих форков, недоступные напрямую через git fetch origin).
2. Создаёт локальную ветку с этим состоянием.
3. Переключается на неё.

Теперь у тебя локально код из этого PR. Можешь запустить тесты, проверить, как код работает в реальном окружении, посмотреть diff в любимом инструменте. Без gh pr checkout это три-четыре ручных команды: добавить remote форка, fetch, checkout, и так далее.

Это особенно ценно для PR из чужих fork'ов: обычный git fetch origin их не видит, потому что они в чужом namespace. gh pr checkout решает это под капотом.

Слить PR

gh pr merge 123                      # интерактивно: какой merge?

gh pr merge 123 --squash             # squash + удалить ветку

gh pr merge 123 --rebase

gh pr merge 123 --merge              # обычный merge commit

gh pr merge 123 --delete-branch      # удалить ветку после

gh pr merge 123 --auto --squash      # дождаться зелёных чеков, потом merge

Стратегии слияния (squash / rebase / merge) подробно - в merge-strategies и главе 17. Флаг --auto особенно полезен: ставишь PR на «merge когда все checks зелёные», и возвращаешься к работе.

Закрыть без merge

gh pr close 123

gh pr close 123 --delete-branch

Полезно, когда понимаешь, что подход неправильный, и переоткроешь PR с другой стороны.

Review через CLI. Удобно для approve/comment, не очень удобно для inline-комментариев на конкретных строках -последнее лучше делать в браузере.

gh pr review 123 --approve                # approve

gh pr review 123 --request-changes -b "..."   # запрос изменений

gh pr review 123 --comment -b "looks good but..."   # комментарий без решения

-b "..." -тело комментария. Можно -F file.md, чтобы взять из файла, удобно для длинных review.

Статус CI

gh pr checks 123                      # таблица всех checks PR

gh pr checks 123 --watch              # обновлять в реальном времени

--watch -полезно, когда ждёшь, пока тесты пройдут перед merge'ом. Терминал показывает прогресс, ты не переключаешься в браузер каждые 30 секунд.

Полезный сценарий: pre-merge

Перед тем как ставить --auto merge, проверь review-состояние и checks одной командой:

gh pr view 123 --json reviewDecision,statusCheckRollup

Вернёт JSON с двумя полями: reviewDecision (APPROVED / CHANGES_REQUESTED / REVIEW_REQUIRED) и список checks. Это основа для самопроверки перед merge или для интеграции в скрипты.

Limitation: inline-комментарии

gh pr review хорошо для overall verdict (approve, request changes, общий коммент). Для построчного review (выделить строку 42 файла foo.py, написать «здесь возможна null pointer») браузер удобнее: drag-select по строкам, кнопка «Add a suggestion» с diff-форматом.

Не пытайся всё делать через gh pr review --body -ты потеряешь привязку к конкретным строкам, и автору PR будет труднее ориентироваться.

gh issue повторяет интерфейс gh pr для issues. Большинство команд один-в-один:

gh issue list                          # открытые issues

gh issue list --state all --label bug  # с фильтрами

gh issue list --author "@me"

gh issue view 142                      # обзор

gh issue view 142 --comments

gh issue view 142 --web

gh issue create                        # интерактивно

gh issue create -t "Login crash" -b "Steps to reproduce: ..." -l bug

gh issue close 142

gh issue reopen 142

gh issue edit 142 -l "wontfix,duplicate"

gh issue edit 142 --add-assignee "@me"

Особенно удобный сценарий -создать issue из терминала, когда что-то нашёл во время работы:

gh issue create -t "TODO refactor parser" -b "context: ..." -l tech-debt

Не нужно переключаться в браузер, потом искать репо, потом открывать форму. Одна команда -issue создан.

Связь issue и PR работает через автоматическое подхватывание ключевых слов в тексте: Closes #142, Fixes #142, Resolves #142 в описании PR -GitHub при merge'е автоматически закроет issue. Когда пишешь PR, добавляй такую строку, чтобы не закрывать issue вручную.

GitHub Actions -CI/CD платформа, живёт в .github/workflows/. Подробности про Actions -в главе 19 (Sprint Git-5). Сейчас достаточно знать, что gh даёт доступ к ним.

gh workflow list                  # все workflows в репо

gh workflow view ci.yml           # детали одного

gh workflow run ci.yml            # запустить вручную (если workflow поддерживает workflow_dispatch)

gh run list                       # история последних runs

gh run list --workflow ci.yml     # только этот workflow

gh run list --branch main         # только на main

gh run view 1234567               # детали run

gh run view 1234567 --log         # полные логи

gh run watch 1234567              # следить в реальном времени

gh run rerun 1234567              # перезапустить failed run

gh run rerun 1234567 --failed     # только failed jobs

Главное преимущество gh здесь -скорость доступа к логам. В UI ты кликаешь на run, потом на job, потом разворачиваешь шаг, ищешь нужную строку в логе. В терминале:

gh run view --log -j 5678   # лог конкретного job

gh run view --log-failed     # только failed-шаги

Это особенно полезно для grep'а по логу:

gh run view 1234 --log | grep -i 'error'

Локально ты получаешь полный текстовый лог в stdout, можешь грепать, считать вхождения, выкидывать в файл. В браузере это делать неудобно.

Главное правило: gh выигрывает в скорости и повторяемости. Браузер выигрывает в визуальной проработке.

gh быстрее, когда

• Создаёшь PR из текущей ветки. gh pr create против браузера: 2 секунды против 30. Каждый PR в день.
• Чекаут чужого PR для тестирования. gh pr checkout 123 -одна команда, особенно ценно для PR из чужих fork'ов.
• Batch-операции по списку. «Все мои открытые PR» - gh pr list --author "@me". В UI это три-четыре клика и потом скролл.
• Скрипты и автоматизация. gh с флагом --json отдаёт машиночитаемый вывод, который можно скормить jq или обрабатывать в bash.
• Просмотр CI-логов. gh run view --log плюс grep - быстрее, чем кликать по UI.
• Создание issue из контекста терминала. Не теряешь фокус.
• Создание репо из существующего каталога. gh repo create --source=. -одна команда, не выходя из cwd.

Браузер удобнее, когда

• Code review с inline-комментариями. Тянуть мышью по строкам, ставить замечания на конкретные строки -в браузере естественно. В CLI больно.
• Обсуждения с несколькими людьми, длинные треды. Читать и форматировать markdown-треды глазами лучше в браузере.
• Большой diff с многими файлами. В UI можно переключаться между файлами, сворачивать неважные. В терминале это менее удобно.
• Изучение незнакомого репо. README + дерево файлов + быстрая навигация по примерам кода. UI заточен под это.
• Настройка repo settings. Большинство admin-операций (branch protection, secrets, webhooks) живёт в UI. Через gh api можно, но это уже скриптовая территория, не повседневная.
• Управление организацией. Members, teams, billing -всё в UI.

Реальный workflow

Эти два пути не конкурируют, они дополняют. Типичная сессия выглядит так: ты пишешь код в редакторе, коммитишь, пушишь - git push. Открываешь PR -gh pr create. Жди review -между делом другая задача. Получил ревью -читаешь его в браузере, потому что там inline-комментарии и контекст. Правишь код, пушишь, прогоняешь снова git push. Чекаешь CI -gh pr checks --watch. Когда зелёно -gh pr merge --squash --delete-branch.

В этом сценарии браузер открывается один раз (на review). Всё остальное -в терминале. Это и есть «gh для скорости, браузер для визуальности».

gh поддерживает алиасы и JSON-вывод. Это превращает его из «удобной обёртки» в «инструмент для автоматизации».

Алиасы

gh alias set co 'pr checkout'

gh alias set pv 'pr view --web'

gh alias set prs 'pr list --author "@me"'

# потом просто

gh co 123     # эквивалент gh pr checkout 123

gh prs        # мои PR

Алиасы хранятся в ~/.config/gh/config.yml. Можно делать сложные алиасы с подстановкой аргументов через $1, $2:

gh alias set 'lab' 'pr list --label "$1" --state open'

gh lab bug    # PR с label bug

JSON-вывод

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

gh pr list --json number,title,author

Вернёт массив объектов JSON. Это вход для jq или питон- скрипта:

# сколько PR у каждого автора?

gh pr list --state all --limit 200 --json author \

  | jq -r '.[].author.login' \

  | sort | uniq -c | sort -rn

# все PR с автором "@me" в виде "номер - заголовок"

gh pr list --author "@me" --json number,title \

  | jq -r '.[] | "#\(.number) \(.title)"'

Список доступных полей gh подскажет, если вместо имён написать что-то невалидное:

gh pr list --json wrong

# gh выведет список валидных полей

Скрипты

Простой пример -скрипт «открой все мои черновики PR в браузере»:

#!/usr/bin/env bash

gh pr list --author "@me" --search "is:draft" --json number \

  | jq -r '.[].number' \

  | xargs -I{} gh pr view {} --web

Или «notify меня, когда CI на текущей ветке станет зелёным»:

gh pr checks --watch && notify-send "PR ready to merge"

Главное преимущество перед прямой работой с GitHub API: gh берёт на себя авторизацию, ретраи, пагинацию. Ты пишешь скрипт без думать про токены и cursors.

Для случаев, когда gh не покрывает фичу (редкие admin-операции, custom GraphQL), есть escape hatch:

gh api repos/cli/cli/contributors --jq '.[].login'

gh api graphql -f query='...'

Это сырой доступ к REST/GraphQL API с авторизацией от gh.