ddadmin
32051ae3f0
- Зачем: - нужно понять, подходит ли GitVerse для управления задачами проекта. - Что: - описаны Public API, совместимость с GitHub и GitLab и доступные операции. - сохранены результаты живых проверок и отличие внутреннего API. - добавлены безопасные команды повторной проверки и решение для dotfiles. - Проверка: - git diff --cached --check.
213 lines
15 KiB
Markdown
213 lines
15 KiB
Markdown
# API GitVerse для задач
|
||
|
||
Проверено 21 июля 2026 года по официальной документации, спецификации OpenAPI,
|
||
ответам действующего сервера и коду веб-интерфейса.
|
||
|
||
## Зачем проверяли
|
||
|
||
Мы хотели понять, можно ли управлять задачами проекта `dotfiles`
|
||
программно и со временем перенести туда часть локального процесса из
|
||
`.scratch`. Для этого нужно было ответить на два вопроса:
|
||
|
||
1. Совместим ли GitVerse с API GitHub или GitLab либо использует свой API?
|
||
2. Можно ли через этот API создавать, менять и закрывать задачи?
|
||
|
||
## Ответ
|
||
|
||
GitVerse предоставляет **собственный REST API** на `https://api.gitverse.ru`.
|
||
Он похож на GitHub REST API по маршрутам и структуре части ответов, но полной
|
||
совместимости GitVerse не заявляет. С GitLab API он несовместим уже на уровне
|
||
маршрутов: GitLab использует `/api/v4/projects/:id/issues`, а GitVerse
|
||
использует `/repos/{owner}/{repo}/issues`.
|
||
|
||
Поддержка задач сейчас неполная: публичный API поддерживает получение списка и
|
||
отдельной задачи, чтение временной шкалы и меток, а также создание и изменение
|
||
комментариев и реакций. В опубликованном контракте нет создания, изменения,
|
||
закрытия или удаления самой задачи. Поэтому заменить им полноценное управление
|
||
задачами пока нельзя.
|
||
|
||
Веб-интерфейс умеет создавать задачи, но использует для этого отдельный
|
||
внутренний API и браузерную сессию. Токен Public API этот внутренний сервер не
|
||
принимает.
|
||
|
||
## Почему комментарии есть, а создания задачи нет
|
||
|
||
GitVerse использует общую модель обсуждений для задач и запросов на слияние.
|
||
Поэтому `GET /repos/{owner}/{repo}/issues/{index}` возвращает любой из этих
|
||
объектов, а комментарии к обоим создаются через
|
||
`POST /repos/{owner}/{repo}/issues/{index}/comments`.
|
||
|
||
Жизненный цикл запросов на слияние вынесен в `/pulls`: там есть создание и
|
||
изменение запроса. Для обычной задачи симметричных `POST /issues` и
|
||
`PATCH /issues/{index}` в Public API нет. Наличие `POST` для комментария не
|
||
означает, что через тот же API можно создать саму задачу.
|
||
|
||
## Как проверяли
|
||
|
||
1. В официальных спецификациях OpenAPI 1.0-1.7 у `/issues` и
|
||
`/issues/{index}` найден только `GET`. Для комментариев опубликованы методы
|
||
записи, а для запросов на слияние есть отдельные методы `/pulls`.
|
||
2. `OPTIONS` для коллекции задач и `/issues/1` вернул `405` с `Allow: GET`.
|
||
Запрос списка без токена вернул `401 Unauthorized` и заголовок
|
||
`GitVerse-Api-Version: 1`.
|
||
3. Токен `work-usa` с правом «Репозитории: Запись» успешно прочитал репозиторий
|
||
через Bearer-аутентификацию: `GET /repos/ddementiev/dotfiles` вернул `200`.
|
||
`GET /user` с тем же токеном вернул `403`, поэтому этот маршрут не подходит
|
||
для проверки токена с ограниченными правами. Basic-аутентификация вернула
|
||
`401`. Токен создан 20 июля 2026 года и действует до 31 декабря 2026 года.
|
||
4. Настоящий `POST /repos/ddementiev/dotfiles/issues` проверен с двумя телами:
|
||
GitHub-подобным и тем, которое отправляет веб-интерфейс. Оба запроса вернули
|
||
`400` и пустую JSON-строку. Такой же ответ получен для заведомо
|
||
несуществующего пути. Ни одна тестовая задача не создалась.
|
||
5. В рабочих JavaScript-модулях GitVerse найден отдельный внутренний API
|
||
веб-интерфейса и точное тело запроса создания задачи. Это наблюдение за
|
||
реализацией сайта, а не публичный контракт.
|
||
6. Безопасный `GET` к внутреннему API с тем же Public API-токеном вернул `401`
|
||
и `{"message":"Wrong auth info"}`. Внутренний клиент использует cookie
|
||
браузерной сессии.
|
||
|
||
## Контракт Public API
|
||
|
||
- Базовый адрес: `https://api.gitverse.ru`. Опубликован собственный контракт
|
||
[GitVerse Public API](https://gitverse.ru/docs/developers/public-api/) и
|
||
[официальный OpenAPI 2.0](https://gitverse.ru/gitverse/rest-api-description/content/master/v1/openapi-1.7.json)
|
||
версии 1.7.0.
|
||
- Обязательны заголовки
|
||
`Authorization: Bearer <TOKEN>` и
|
||
`Accept: application/vnd.gitverse.object+json;version=1`.
|
||
Токен создается в профиле: «Настройки» → «Управление токенами»;
|
||
[инструкция по токенам](https://gitverse.ru/docs/collaborative/authentification/tokens/)
|
||
предлагает включить доступ к репозиториям.
|
||
- Лимит составляет 2000 запросов в час на идентификатор авторизованного
|
||
пользователя.
|
||
При превышении сервер отвечает `429` и передает остаток, время сброса и
|
||
`Retry-After`; см. [официальное описание ограничений](https://gitverse.ru/docs/developers/public-api/using-public-api/rate-limits).
|
||
- Для списков используются `page`, `per_page` и заголовок ответа `Link`.
|
||
Верхняя граница `per_page` в открытом контракте не указана.
|
||
|
||
### Опубликованные операции с задачами
|
||
|
||
| Метод | Маршрут | Назначение |
|
||
|---|---|---|
|
||
| `GET` | `/repos/{owner}/{repo}/issues` | Список задач и запросов на слияние; фильтры `state`, `q`, `labels`, `milestones`, `created_by`, `assigned_by`, `mentioned_by`, `type`, `since`, `before`, `page`, `per_page` |
|
||
| `GET` | `/repos/{owner}/{repo}/issues/{index}` | Одна задача или запрос на слияние |
|
||
| `GET` | `/repos/{owner}/{repo}/issues/{index}/timeline` | Комментарии и события задачи |
|
||
| `GET` | `/repos/{owner}/{repo}/issues/{index}/labels` | Метки задачи |
|
||
| `GET`, `POST` | `/repos/{owner}/{repo}/issues/{index}/comments` | Список и создание комментариев |
|
||
| `GET` | `/repos/{owner}/{repo}/issues/comments/{id}` | Один комментарий |
|
||
| `PATCH`, `DELETE` | `/repos/{owner}/{repo}/issues/{index}/comments/{comment_id}` | Изменение и удаление комментария |
|
||
| `POST` | `/repos/{owner}/{repo}/issues/{index}/comments/{comment_id}/reactions` | Добавление реакции |
|
||
| `DELETE` | `/repos/{owner}/{repo}/issues/{index}/comments/{comment_id}/reactions/{reaction_id}` | Удаление реакции |
|
||
|
||
Источник таблицы: раздел `paths` официальной
|
||
[спецификации OpenAPI 1.7](https://gitverse.ru/gitverse/rest-api-description/content/master/v1/openapi-1.7.json).
|
||
|
||
### Подробности проверки создания
|
||
|
||
Токен взят из локального хранилища Git. Его значение не печаталось и не
|
||
сохранялось в документе.
|
||
|
||
- `GET https://api.gitverse.ru/repos/ddementiev/dotfiles` с Bearer-токеном
|
||
вернул `200`. Это подтверждает, что Public API принимает токен и видит
|
||
репозиторий.
|
||
- `POST https://api.gitverse.ru/repos/ddementiev/dotfiles/issues` с
|
||
GitHub-подобным телом `title` и `body` вернул `400` и пустую JSON-строку.
|
||
- Повторный `POST` с точным форматом веб-интерфейса (`title`, `content`,
|
||
`issue_type`, `assignees`, `labels` и `attachments`) вернул тот же ответ.
|
||
- Такой же `400` сервер возвращает для `POST` на заведомо несуществующий путь.
|
||
Поэтому этот ответ выглядит как общая обработка незарегистрированного метода,
|
||
а не как ошибка полей задачи.
|
||
- Ни одна тестовая задача не была создана.
|
||
|
||
Код [веб-интерфейса задач](https://gitverse.ru/ddementiev/dotfiles/issues)
|
||
показывает другую точку входа:
|
||
|
||
```text
|
||
https://gitverse.ru/sc/sbt/api/v1/repos/{owner}/{repo}/issues
|
||
```
|
||
|
||
Форма отправляет туда `POST` с телом следующего вида:
|
||
|
||
```json
|
||
{
|
||
"title": "...",
|
||
"content": "...",
|
||
"issue_type": 1,
|
||
"assignees": [],
|
||
"labels": [],
|
||
"attachments": []
|
||
}
|
||
```
|
||
|
||
Внутренний клиент передает cookie браузерной сессии. Проверочный `GET` к этому
|
||
адресу с токеном `work-usa` вернул `401` и
|
||
`{"message":"Wrong auth info"}`. Эта проверка не запускала внутренний `POST` и
|
||
не могла создать задачу. Она показала, что токен Public API не подходит для
|
||
клиента веб-интерфейса.
|
||
|
||
## Как повторить безопасные проверки
|
||
|
||
Токен должен находиться в переменной `GITVERSE_TOKEN`. Команды ниже только
|
||
читают данные и не создают задач.
|
||
|
||
```bash
|
||
curl -sS -o /dev/null -w '%{http_code}\n' \
|
||
-H "Authorization: Bearer $GITVERSE_TOKEN" \
|
||
-H 'Accept: application/vnd.gitverse.object+json;version=1' \
|
||
https://api.gitverse.ru/repos/ddementiev/dotfiles
|
||
|
||
curl -sS -X OPTIONS -D - -o /dev/null \
|
||
-H "Authorization: Bearer $GITVERSE_TOKEN" \
|
||
-H 'Accept: application/vnd.gitverse.object+json;version=1' \
|
||
https://api.gitverse.ru/repos/ddementiev/dotfiles/issues
|
||
```
|
||
|
||
Ожидаются `200` для первого запроса и `405` с `Allow: GET` для второго.
|
||
Повторять `POST` в основном репозитории не следует: если GitVerse добавит метод,
|
||
проверка создаст настоящую задачу. Для новой проверки нужен временный
|
||
репозиторий.
|
||
|
||
## Совместимость
|
||
|
||
- Это не GitLab API. У GitLab базовый путь начинается с `/api/v4`, а создание
|
||
задачи выполняется через `POST /projects/:id/issues`; см.
|
||
[GitLab REST API](https://docs.gitlab.com/api/rest/) и
|
||
[Issues API](https://docs.gitlab.com/api/issues/).
|
||
- Это не совместимая замена GitHub API. Совпадают некоторые маршруты и поля,
|
||
но отличаются хост, MIME-тип, версия и полнота операций. Например, GitHub
|
||
документирует `POST /repos/{owner}/{repo}/issues` и изменение задачи, а
|
||
GitVerse для этого маршрута публикует только `GET`; см.
|
||
[GitHub Issues API](https://docs.github.com/en/rest/issues/issues).
|
||
- Сходство с GitHub намеренное и частичное: в документации GitVerse некоторые
|
||
дубли полей ответа прямо объясняются
|
||
[совместимостью с GitHub API](https://gitverse.ru/docs/developers/public-api/repositories/api-post-orgs-repos).
|
||
Это не обещание полной совместимости клиента или контракта.
|
||
|
||
## Решение для dotfiles
|
||
|
||
- Оставить `.scratch` главным хранилищем задач текущей ветки.
|
||
- Public API можно использовать для чтения задач. Операции с комментариями
|
||
опубликованы, но перед постоянным использованием их стоит отдельно проверить
|
||
на тестовой задаче.
|
||
- Не строить интеграцию на внутреннем `/sc/sbt/api/v1`. Он требует браузерную
|
||
сессию, не документирован и может измениться без предупреждения.
|
||
- Вернуться к переносу `.scratch` в GitVerse после появления официальных
|
||
методов создания и изменения задач.
|
||
|
||
## Неизвестно и требует уточнения у GitVerse
|
||
|
||
- Есть ли закрытая бета или планируемый публичный `POST/PATCH` для задач.
|
||
- Какие права будут нужны для создания задач, если метод появится. Токен с
|
||
правом «Репозитории: Запись» успешно читает репозиторий, но проверить еще не
|
||
опубликованную операцию невозможно.
|
||
- Поддержит ли GitVerse обычные GitHub-клиенты при замене базового адреса.
|
||
Официального заявления об этом не найдено, а различия контракта уже исключают
|
||
надежную совместимость.
|
||
- [GitVerse MCP](https://gitverse.ru/docs/ai/mcp/) использует тот же токен и
|
||
собственный адрес `https://mcp.gitverse.ru`, но официальный список его
|
||
сущностей на 21 июля 2026 года не включает задачи. По документации это не
|
||
обход отсутствующих операций REST API.
|
||
|
||
Следующий шаг: запросить у поддержки GitVerse сроки появления публичных
|
||
операций создания и изменения задач, а также нужные права токена.
|