GitHub — репозитории, файлы, issues и pull requests

Навык GitHub позволяет работать с выбранным репозиторием из чата: читать и скачивать файлы, готовить commit, создавать и изменять issues и pull requests (PR), оставлять комментарии и reviews, смотреть результаты CI и сливать PR. Искра действует от вашего имени и в пределах прав вашего GitHub-токена. Каждое изменение требует отдельного решения в форме подтверждения.

Подключение

1. Откройте «Навыки» → «Каталог», найдите GitHub и установите его в личный профиль. Если каталог в вашей Искре выключен, включите GitHub в списке доступных навыков. Подключение всегда личное: даже установка организацией не заменяет токен каждого пользователя.
2. Создайте в GitHub personal access token (PAT). Для подходящих ему задач используйте fine-grained token: выберите владельца, нужные репозитории, срок действия и права только для своих операций. Порядок создания описан в инструкции GitHub.
3. Откройте настройки навыка и введите PAT в защищённое поле подключения GitHub. Токен вводится только в эту форму: не вставляйте его в чат, файлы или комментарии. Искра не возвращает значение токена в ответах, созданных файлах и обычных журналах.
4. Попросите: «Проверь подключение GitHub и выбери репозиторий my-team/project». При выборе нового репозитория проверьте его полное имя в форме.

В настройках подключения нужен только PAT. Репозиторий и, для работы с файлами или историей, нужную ветку либо версию указывайте в поручении. Искра может взять их из однозначного контекста разговора; если данных недостаточно, она уточнит цель. Сохранённые в прежней версии настройки репозитория и ветки больше не используются; повторно вводить PAT после обновления не нужно.

Минимальные права зависят от действия:

Права токена не расширяют ваши права в GitHub. Организация может требовать одобрения токена; до одобрения доступ к закрытым репозиториям не появится. Для classic PAT организация с SSO может требовать отдельной авторизации токена. Для отдельных видов проверок, fork и изменений файлов workflow GitHub может потребовать дополнительные права или другой поддерживаемый тип токена. Сверяйтесь с правами конкретных API GitHub, если доступ к части действий отклонён.

Навык работает с вашим PAT и не списывает отдельные МТ за обращение к GitHub. Обычная работа Искры в чате учитывается по условиям вашего плана. В облачной Искре MCP-запросы к GitHub проходят через ретранслятор Искры iskra-github.duckdns.org. Он принимает ваш PAT и запрошенные данные для передачи GitHub по HTTPS; токен и содержимое запросов не сохраняются в его журналах. Остальные запросы идут напрямую к GitHub. В установленной у вас Искре подключение идёт напрямую к GitHub; общий навык не включает облачный ретранслятор. Для подключения нужен внешний сетевой доступ.

Выбор репозитория и чтение

При первом обращении к новому репозиторию Искра просит подтвердить его выбор для этого профиля. Это подтверждение не задаёт репозиторий по умолчанию: цель следующего поручения определяется самим поручением и контекстом. В результате Искра указывает полное имя owner/repository и, когда действие связано с файлами, ветку или версию. Перед записью проверьте их в форме: одинаковое короткое имя бывает у разных владельцев.

Примеры поручений:

• «В my-team/project, ветка release, покажи README и последние commits».
• «Скачай docs/guide.pdf из my-team/project на ветке release».
• «Найди открытые issues про экспорт в my-team/project».
• «Покажи diff, reviews и результаты проверок PR №42 в my-team/project».
• «Покажи неуспешные задания последнего запуска CI и конец их логов».

Скачанный файл появляется среди артефактов чата. Предел одного файла — 3 МиБ; слишком большой файл Искра отклонит до сохранения. Каталог показывает содержимое запрошенной папки, а не обязательно всё дерево репозитория. Списки и логи могут приходить частями: признаки has_more или truncated означают неполную выдачу. Попросите следующую страницу или сузьте запрос; отсутствие объекта в таком ответе не доказывает, что объекта нет.

Изменения и подтверждение

Для записи Искра сначала показывает форму с репозиторием, целью и точными изменениями. Проверьте её и подтвердите действие. Отказ, закрытие формы или отсутствие ответа не отправляют запись. Установка навыка и режим его включения не заменяют это подтверждение.

• Репозитории и ветки: создание репозитория, fork или новой ветки с явно показанным исходным commit и местом назначения.
• Файлы: добавление, изменение, удаление и переименование одним commit. Можно использовать файл текущего чата. Форма показывает пути, изменения, исходную версию ветки и сообщение commit; для двоичных файлов — размер и контрольную сумму. Одна операция включает до 20 изменений и до 3 МиБ новых данных. Если вершина ветки изменилась после подготовки, весь commit отклоняется: нужно получить свежую версию и заново подтвердить изменения.
• Issues и PR: создание, редактирование заголовка и описания, смена состояния, обычные комментарии. У issues можно добавлять и снимать метки и исполнителей; неуказанные метки и исполнители сохраняются. Логин исполнителя в форме показан в нижнем регистре: GitHub не различает регистр логина, и в этом же виде Искра сверяет результат.
• Review: чтение обсуждений и отправка review PR целиком. Создание построчных комментариев в незавершённом review пока недоступно.
• Merge: отдельное подтверждение конкретной версии PR и способа слияния. Если вершина PR изменилась, слияние отклоняется. Правила защиты веток, необходимые проверки и права GitHub продолжают действовать.

Несколько действий, например закрыть issue и добавить метку, подтверждаются по отдельности. Искра не обещает общую транзакцию для разных действий. Успешный результат содержит ссылку на объект или commit и наблюдаемый итог.

Конфликт заголовка или описания

Перед изменением title/body Искра показывает прежний и новый текст, затем снова проверяет объект. Если он уже изменился, запись останавливается до отправки. После отправки Искра перечитывает результат и сообщает о выявленном расхождении.

Для этих полей GitHub не даёт такой же проверки версии при записи, как для файлового commit. Между последним чтением и изменением остаётся короткое окно: чужая одновременная правка может быть перезаписана, и это не всегда удастся обнаружить. Для совместно редактируемого текста согласуйте работу с коллегами; при расхождении откройте ссылку и сравните актуальный текст. Искра не делает автоматический откат или повторную перезапись.

Если исход неизвестен

Связь может оборваться после того, как GitHub уже выполнил действие. Тогда Искра сообщает «исход неизвестен», сохраняет сведения об операции и проверяет GitHub чтением. Попросите «проверь результат этой операции»; если у вас есть ссылка на созданный объект, приложите её для проверки. Это не запускает действие повторно.

Неполный список, отсутствие найденного совпадения или неоднозначный ответ не превращают неизвестный исход в неуспех. Если вам нужно другое самостоятельное действие, выберите в форме новое независимое действие и подтвердите его полное содержание. Прежний неизвестный исход останется сохранённым; новая операция не отменяет его и может добавить ещё один объект в GitHub.

Если Искра сообщает, что место для истории операций исчерпано, новая запись не отправляется. Сохраните сообщение и обратитесь к администратору; ранее неизвестные исходы при этом не сбрасываются.

Если во время открытой формы подключить другой аккаунт GitHub, подтверждённое действие не отправляется: форма и её содержимое собраны на прежнем подключении. Повторите просьбу — Искра соберёт форму заново под текущий аккаунт.

Ограничения и ошибки доступа

Навык работает с GitHub.com через PAT. OAuth-вход, GitHub Enterprise, запуск или перезапуск workflows, удаление репозитория и фоновая синхронизация не входят в его возможности. Читать результаты GitHub Actions можно.

Отказ доступа может быть связан с PAT, правилами организации или сетевым доступом к сервисам GitHub. Проверьте срок токена, выбранного владельца и репозитории, права на нужное действие, одобрение организации и правила защиты ветки. Если тот же токен работает вне Искры, сообщите об этом поддержке: одного отказа доступа недостаточно, чтобы заключить, что нужны дополнительные права. Передавайте текст ошибки без токена. При ограничении частоты запросов дождитесь указанного GitHub срока; неизвестную запись сначала проверяйте чтением. Искра не повторяет часть записи и не откатывает её автоматически.