openclaude-LLM-local/docs/openclaude-with-repositories.md

OpenClaude и Git-репозитории

Как организовать работу OpenClaude с GitHub/GitLab/Gitea и похожими сервисами.

1) Что значит "научить OpenClaude работать с репозиториями"

Обычно это 3 уровня:

1. Локальный уровень: OpenClaude работает в локальном git-репозитории (clone, branch, commit).
2. Remote уровень: пуш/PR/issue через токены и CLI (gh, glab, tea).
3. Контекст и автоматизация: доступ к данным репозитория через MCP-инструменты.

2) Базовая схема (рекомендуется)

• Клонировать репозиторий локально.
• Запускать OpenClaude из корня проекта.
• Для GitHub использовать gh auth login.
• Для GitLab использовать glab auth login.
• Для Gitea использовать SSH-ключи или PAT в remote URL/credential manager.

Это даёт OpenClaude полный цикл: читать код, редактировать, запускать тесты, делать коммиты и PR.

3) Настройка аутентификации без постоянного ввода пароля

Подробный SSH-гайд с типовыми ошибками:

• docs/github-ssh-setup-and-troubleshooting.md

GitHub

gh auth login
gh auth status

GitLab

glab auth login
glab auth status

Универсально для git HTTPS

git config --global credential.helper store

Лучше и безопаснее - SSH:

ssh-keygen -t ed25519 -C "you@example.com"
# добавить публичный ключ в GitHub/GitLab/Gitea
git remote set-url origin git@github.com:OWNER/REPO.git

4) Минимальный безопасный процесс работы с кодом

1. Создать отдельную feature-ветку.
2. Делать небольшие коммиты с понятными сообщениями.
3. Перед push запускать тесты/lint.
4. Не хранить секреты в репозитории (.env, ключи, токены).
5. Для main/master включить protected branch и PR review.

5) Как подключить репозиторий как источник знаний (RAG)

Если цель - чтобы OpenClaude "знал проект":

• индексировать README, docs, ADR, API-контракты, runbook
• не индексировать шум (node_modules, dist, lock-файлы без необходимости)
• регулярно переиндексировать после merge крупных изменений

Простой путь:

• git clone репозиторий
• копировать нужные папки в docs/rag-mcp-starter/docs
• запускать index.py
• использовать search_docs и answer_with_citations

6) MCP для Git-платформ: что имеет смысл добавить

Полезные MCP-инструменты:

• list_prs(repo)
• get_pr_diff(repo, pr_number)
• list_issues(repo, label)
• create_issue(repo, title, body)
• comment_pr(repo, pr_number, body)
• get_file_at_ref(repo, path, ref)

Такой слой позволяет OpenClaude работать не только с локальным checkout, но и с удаленным контекстом.

7) Практика для self-hosted Git (Gitea/Forgejo/GitLab self-hosted)

1. Убедиться в доступности API/SSH с сервера.
2. Создать сервисный токен с минимальными правами (least privilege).
3. Хранить токен в переменных окружения или secrets manager.
4. Ограничить доступ по IP/ACL.
5. Вести аудит действий (кто/когда создал PR/comment/push).

8) Частые ошибки

• OpenClaude запущен не из корня репозитория.
• Нет прав на push в remote.
• PAT истек или не имеет scope для PR/issues.
• Смешивание нескольких аккаунтов в одном credential helper.
• Отсутствуют локальные зависимости проекта (тесты не запускаются).

GitHub CLI: Could not resolve to a Repository или Repository not found

На вашей машине gh repo view OWNER/REPO может работать (например, после gh auth login или с корректным классическим token), а в другой среде (CI, удалённый агент, «облачная» сессия без вашего локального credential store) — нет: там часто нет той же авторизации или репозиторий приватный и для этой среды не выдан доступ.

Что проверить:

1. Fine-grained PAT: в разделе доступа к репозиториям явно добавлен нужный репозиторий (или группа «All repositories», если так задумано). Один только заголовок в UI не гарантирует, что токен передан в ту среду, где выполняется команда.
2. Permissions: для gh repo view как минимум чтение метаданных репозитория (в терминах GitHub — Metadata read и при необходимости Contents read).
3. Контекст агента: удалённый агент должен работать в workspace = клон нужного репозитория и иметь способ подставить токен (GH_TOKEN, gh auth login в этой среде и т.д.). Локальный успех команды у вас в PowerShell не переносится автоматически в облако.

Если цель — чтобы автоматизация сама делала коммиты/PR в приватный репозиторий, выдайте секрет с PAT в этой среде и ограничьте права токена минимально необходимыми scope.

9) Рабочий чек-лист перед началом

git status
git remote -v
gh auth status || true
glab auth status || true

Если всё ок - можно давать OpenClaude задачи на полный цикл "изменение -> тест -> commit -> PR".