PTah
131 lines
6.7 KiB
Markdown
131 lines
6.7 KiB
Markdown
# 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
|
||
|
||
```bash
|
||
gh auth login
|
||
gh auth status
|
||
```
|
||
|
||
### GitLab
|
||
|
||
```bash
|
||
glab auth login
|
||
glab auth status
|
||
```
|
||
|
||
### Универсально для git HTTPS
|
||
|
||
```bash
|
||
git config --global credential.helper store
|
||
```
|
||
|
||
Лучше и безопаснее - SSH:
|
||
|
||
```bash
|
||
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) Рабочий чек-лист перед началом
|
||
|
||
```bash
|
||
git status
|
||
git remote -v
|
||
gh auth status || true
|
||
glab auth status || true
|
||
```
|
||
|
||
Если всё ок - можно давать OpenClaude задачи на полный цикл "изменение -> тест -> commit -> PR".
|