gh-issue-sync CLI
Go-утилита для issues GitHub: они лежат на диске файлами Markdown, агент правит их пачкой, а команда push отправляет итог на сайт.
- 169 ★ репозитория
- Последний коммит
- Apache-2.0
Расширенный доступ
Почему такой уровень
- `push` создает и меняет issues, метки и вехи на GitHub от вашего имени; до отправки правки остаются локальными.
Установка
- Работает в
Ручная установка
curl -sSfL https://github.com/mitsuhiko/gh-issue-sync/releases/latest/download/install.sh | shПервый вариант из README для macOS и Linux; нужен авторизованный `gh`.
Доступ и проверки
Как мы проверяемРасширенный доступИнструмент запускает код или ходит в сеть, а внешние данные только читает.
- `push` создает и меняет issues, метки и вехи на GitHub от вашего имени; до отправки правки остаются локальными.
Это чужой код. Посмотрите файлы в репозитории перед установкой.
Что делает
`gh-issue-sync` зеркалирует issues репозитория в папку `.issues/` как Markdown-файлы с YAML-шапкой: заголовок, метки, исполнители, веха и состояние. Файлы лежат в `open/` и `closed/`, номер берется из имени файла. Правите их в редакторе или поручаете агенту, затем `gh-issue-sync push` отправляет изменения на GitHub, а `pull` забирает чужие. Новые issues создаются локально с временными номерами вида `T42`, после отправки получают настоящие, и ссылки вроде `#T42` в других файлах заменяются сами. Сверка идет по трем версиям (локальная, исходная и удаленная). При конфликте файл пропускается с предупреждением. Команда `write-skill` кладет готовый скилл в каталог Claude Code, Codex, OpenCode, Pi или Amp, чтобы агент знал команды. Работает поверх авторизованного `gh`.
Для кого. Мейнтейнерам с накопившимися issues, которые хотят довести формулировки с помощью Claude Code или Codex и отправить правки одной операцией.
Подходит, если
- Полсотни issues требуют единых заголовков и меток, и агент правит их локально.
- Backlog надо разобрать офлайн: поиск по тексту и меткам идет по файлам на диске.
- Из заметок рождается десяток новых issues, и их заводят черновиками без номеров.
- Агент закрывает дубликаты: перенос файла из `open/` в `closed/` или команда `close --reason not_planned`.
- Нужна резервная копия всех открытых issues в читаемом виде внутри репозитория.
Не подходит, если
- Issues редактируют разные люди одновременно: при расхождении файл пропускается, а разбор конфликтов остается ручным.
- Агенту хватает точечных действий в GitHub: проще обернуть `gh` или подключить MCP-сервер GitHub.
- Нет авторизованного `gh`: утилита опирается на него и без входа не работает.
Пример запроса к агенту
Подтяни issues, найди среди открытых дубликаты и просьбы без описания, дополни их в файлах `.issues/open/` и покажи `gh-issue-sync status` до отправки.Ограничения
Нужен установленный и авторизованный GitHub CLI `gh`; для синхронизации Projects понадобится `gh auth refresh -s project`. Конфликт локальных и удаленных правок не сливается автоматически: файл пропускается с предупреждением, а перезапись включается через `--force`. Автор указывает, что код целиком создан нейросетью и вопрос его защиты авторским правом остается неясным. Последний коммит в репозитории — март 2026 года.
Как отключить. Удалите бинарник `gh-issue-sync`, папку `.issues/` в репозитории и скилл из каталога агента (команда `write-skill` печатает путь установки).
Частые вопросы
Как поставить gh-issue-sync?
Выполните `curl -sSfL https://github.com/mitsuhiko/gh-issue-sync/releases/latest/download/install.sh | sh` на macOS или Linux. Есть и `go install github.com/mitsuhiko/gh-issue-sync/cmd/gh-issue-sync@latest`, а также готовые бинарники в релизах.
Как научить Claude Code пользоваться утилитой?
Выполните `gh-issue-sync write-skill --agent claude`. Скилл попадет в `~/.claude/skills/`, а с флагом `--scope project` в `.claude/skills/` проекта.
Что произойдет при конфликте правок?
Если файл изменен и локально, и на GitHub, при `pull` и `push` он пропускается с предупреждением. Чтобы перезаписать локальную версию удаленной, используйте `--force`.
Как создать issue без номера?
Командой `gh-issue-sync new "Название"` или файлом с именем на `T`, например `T1a2b3c-my-issue.md`. После `push` файл получает настоящий номер, а ссылки `#T1a2b3c` обновляются.
Как отфильтровать issues?
`gh-issue-sync list --label bug --assignee alice` или поиск в синтаксисе GitHub: `--search "error no:assignee sort:created-asc"`. Ключ `--all` добавляет закрытые.
Обсуждение
Вопросов и отзывов пока нет.
Похожие
CLI-инструментыСкиллы GitHub CLI
GitHub CLI skills (gh, gh-skill)
Официальные скиллы GitHub CLI: как агенту правильно вызывать gh и как управлять скиллами командой gh skill
Расширение GitHub CLI и скилл для агентов: загружает скриншоты, PDF, архивы и логи в задачи и запросы на слияние из терминала и возвращает готовую ссылку
Расширение GitHub CLI gh stack и скилл для агента: цепочка зависимых веток и PR, перебазирование, отправка и слияние всего стека целиком
Панель GitHub в терминале показывает задачи и запросы на слияние для ручного разбора работы агента в настраиваемых разделах.
CLI и MCP-сервер ищут по исходникам пакетов и репозиториев, читают файлы и показывают примеры с указанием источников.
Личный набор автора: общие правила для агентов и десятки скиллов для GitHub, браузера, macOS, сообщений и релизов, плюс скрипт синхронизации
Сравнение с похожими
Карточки с тем же главным запросом: чем они отличаются.
| Инструмент | Официальный | Авторизация | Звезды репозитория | Главное отличие |
|---|---|---|---|---|
| gh-issue-sync (эта карточка) | нет | 169 | ||
| gh-axi | нет | 359 | обертка над `gh` с компактным выводом для работы онлайн; здесь issues хранятся файлами и правятся офлайн | |
| GitHub MCP Server | нет | ключ необязателен | 34 279 | дает агенту вызовы GitHub API; `gh-issue-sync` синхронизирует issues с локальной папкой Markdown |
Коротко о README
README объясняет, зачем работать с issues локально, и ведет от установки через быстрый старт к описанию синтаксиса поиска, временных номеров и таблицы разрешения конфликтов. Отдельный раздел посвящен установке скилла в разные агенты.
Бейдж для README
Исходный SKILL.md
--- name: gh-issue-sync description: "Manage GitHub issues locally as Markdown files. Use for triaging, searching, editing, and creating issues without leaving your editor or terminal." --- # gh-issue-sync Syncs GitHub issues to local Markdown files in `.issues/open/` and `.issues/closed/`. ## Commands ``` gh-issue-sync init # Initialize in git repo gh-issue-sync pull # Fetch open issues (--all for closed too) gh-issue-sync push # Push local changes (--dry-run to preview) gh-issue-sync list # List issues (supports gh issue list flags + --search) gh-issue-sync new "Title" # Create issue (--label, --edit) gh-issue-sync close 42 # Close (--reason completed|not_planned) gh-issue-sync reopen 42 gh-issue-sync status # Show local changes gh-issue-sync diff 42 # Show diff (--remote to re-fetch) ``` ## File Format `.issues/open/42-fix-login-bug.md`: ```markdown --- title: Fix login bug labels: [bug, priority:high] assignees: [alice] milestone: v1.0 state: open # For closed: state_reason: completed|not_planned # Optional: parent: 10, blocked_by: [11, 12], blocks: [15] --- Issue body in Markdown. ``` Issue number is derived from the filename, not stored in frontmatter. ## Temporary Issues New issues get a `T`-prefixed ID (e.g., `T1a2b3c`). The filename must start with `T`: ``` .issues/open/T1a2b3c-my-new-issue.md ``` On `push`, the file is renamed to the real issue number (e.g., `42-my-new-issue.md`) and `number:` in frontmatter is updated. Any `#T1a2b3c` references in other issues are also updated to `#42`.