Справка по объектам публичного API задач, проектов и запросов на слияние

Данный документ описывает объекты (структуры ответов) публичного API GitVerse, которые встречаются в примерах ответов документации четырех разделов:

  • общие методы для задач и запросов на слияние (issues, PR, комментарии, реакции, метки, таймлайн, вложения);

  • методы, применяемые только к задачам (types, родительская задача, подзадачи, метки задачи, реакции, вложения, связанная разработка);

  • методы работы с запросами на слияние (files, commits, reviews, комментарии в PR, status merge);

  • методы работы с проектами (Kanban-доски: проекты, колонки, привязка задач к проектам).

Объекты взаимно переиспользуются между файлами: одна и та же логическая сущность (например, пользователь, метка, репозиторий, комментарий) появляется в ответах разных методов и в разных вложенных контекстах. Ниже построен граф этих объектов и приведено описание каждого из них.


1. User (Пользователь)

Один из самых переиспользуемых объектов. Появляется как:

  • автор задачи issue.user и исполнители assignee/assignees;
  • автор комментария comment.user;
  • автор реакции reaction.user;
  • автор/исполнитель/ревьюер/«сливший» PR (user, assignees, requested_reviewers, merged_by);
  • автор и коммиттер коммита (author, committer);
  • автор ревью review.user;
  • владелец комментария/резолвер в ReviewComment;
  • пользователь в событии таймлайна.

В документации встречаются три варианта структуры.

1.1. Базовая структура (используется в issue, комментариях)

ПолеТипОписание
idintegerУникальный идентификатор пользователя
namestringОтображаемое имя
loginstringЛогин (username)
typestringТип аккаунта (User, Organization и т.п.)
biostringБиография
emailstring / nullEmail
avatar_urlstringСсылка на аватар
html_urlstringСсылка на профиль в веб-интерфейсе
urlstringAPI-ссылка на пользователя
followers_urlstringСсылка на список подписчиков
following_urlstringСсылка на список подписок
repos_urlstringСсылка на список репозиториев
organizations_urlstringСсылка на список организаций
site_adminbooleanЯвляется ли администратором GitVerse
locationstring / nullМестоположение
is_verifiedbooleanПроверенный ли аккаунт
followersintegerКоличество подписчиков
followingintegerКоличество подписок
public_reposintegerКоличество публичных репозиториев
stars_countintegerКоличество звезд
created_atstring (date-time)Дата регистрации (RFC 3339)
updated_atstring (date-time)Дата последнего обновления

1.2. Расширенная структура (вместо location/name использует full_name, website; используется в PR-объектах и ревью)

ПолеОписание
loginЛогин пользователя
idУникальный идентификатор
avatar_urlСсылка на аватар
html_urlСсылка на профиль
urlAPI-ссылка
typeТип аккаунта
name / full_nameИмя пользователя
bio, email, location, websiteКонтактные данные
followers, following, public_repos, stars_countСчетчики
followers_url, following_url, organizations_url, repos_url, starred_url, subscriptions_urlСсылки на подразделы
site_admin, is_verifiedФлаги
created_at, updated_atДаты

Примечание: в ряде компактных ответов (например, в событии таймлайна типа comment или в сокращенных вложениях) объект user приводится сокращенно — только { "id": ..., "login": ... }.


2. Repository (Репозиторий)

В документации встречаются три варианта вложенности.

2.1. Базовая структура (в issue.repository)

ПолеТипОписание
idintegerУникальный идентификатор репозитория
namestringНазвание репозитория
ownerstringЛогин владельца
full_namestringПолное имя owner/name

2.2. Вариант «ref» (в base.repo / head.repo PR)

ПолеТипОписание
idintegerИдентификатор репозитория
namestringНазвание
full_namestringowner/name
ownerobjectКраткий объект владельца (id, login, avatar_url, html_url, type)
privatebooleanПриватность
descriptionstring / nullОписание
default_branchstringВетка по умолчанию
html_urlstringСсылка в веб-интерфейсе
urlstringAPI-ссылка

2.3. Расширенная структура (в development веток и PR, в ответе создания PR)

Содержит все поля варианта «ref», а также:

ПолеТипОписание
forkbooleanЯвляется ли форком
forks, forks_countintegerКоличество форков
languagestring / nullОсновной язык
stargazers_countintegerЗвезды
watchers, watchers_countintegerНаблюдатели
sizeintegerРазмер
open_issues, open_issues_countintegerОткрытые задачи
is_templatebooleanШаблонный ли
topicsarrayТемы
archived, disabledbooleanФлаги состояния
visibilitystringВидимость (public/private)
pushed_atstringДата последнего push
has_issues, has_wiki, has_projects, has_pages, has_downloads, allow_forkingbooleanВозможности репозитория
homepagestring / nullДомашняя страница
licenseobject / nullЛицензия (key, name, spdx_id, url)
created_at, updated_atstringДаты
allow_merge_commit, allow_squash_merge, allow_rebase_merge, delete_branch_on_mergebooleanНастройки слияния
clone_url, ssh_url, mirror_urlstringURL клонирования
contents_url, forks_url, hooks_url, issue_comment_url, issues_url, languages_url, pulls_urlstringAPI-ссылки на подразделы
permissionsobjectПрава (pull, push, admin, maintain, triage)
role_namestringРоль текущего пользователя
template_repository, parentobject / nullСвязанные репозитории

3. Milestone (Веха)

Появляется в: задаче (milestone), событии таймлайна (old_milestone/milestone), а также как корневой объект методов работы с вехами (/milestones, /milestones/{id}).

Веха привязывается к задачам: ее назначают задаче при создании или обновлении (поле milestone) либо через методы привязки задач к вехам. В объектах запросов на слияние поле milestone обычно null.

ПолеТипОписание
idintegerИдентификатор вехи
titlestringНазвание
descriptionstring / nullОписание
statestringСостояние (open / closed)
due_onstring (date-time) / nullСрок выполнения
created_atstring (date-time)Дата создания
updated_atstring (date-time)Дата обновления
closed_atstring (date-time) / nullДата закрытия
open_issuesintegerОткрытые задачи
closed_issuesintegerЗакрытые задачи

4. Label (Метка)

Появляется в: задаче (labels[]), PR (labels[]), подзадаче, событии таймлайна, а также как корневой объект методов работы с метками (/labels, /labels/{name}).

4.1. Базовая структура (в составе задач/PR)

ПолеТипОписание
idintegerИдентификатор метки
namestringНазвание
descriptionstringОписание
colorstringЦвет (hex без #)
exclusivebooleanПризнак исключительности метки
is_archivedbooleanЗаархивирована ли
urlstringAPI-ссылка на метку

4.2. Расширенная структура (ответ создания/редактирования метки)

ПолеТипОписание
idintegerИдентификатор метки
node_idstringГлобальный ID узла (всегда null)
urlstringAPI-ссылка
namestringНазвание
descriptionstringОписание
colorstringЦвет (hex без #)
defaultboolean / nullСоздана ли по умолчанию (всегда null)
exclusivebooleanПризнак исключительности

5. IssueType (Тип задачи)

Появляется как корневой объект /orgs/{org}/issue-types и как вложенный type в задаче.

5.1. Базовая структура (в объекте задачи)

ПолеТипОписание
idintegerИдентификатор типа
codestringКод типа
namestringНазвание
colorstringЦвет

5.2. Расширенная структура (эндпоинт типов)

ПолеТипОписание
idintegerИдентификатор типа
node_idstringГлобальный ID узла (всегда null)
codestringКод типа (task, bug, story, epic)
namestringНазвание типа
descriptionstring / nullОписание (всегда null)
colorstringЦвет типа

6. Attachment (Вложение / Файл)

Появляется в: задаче (assets[], attachments[]), комментарии (attachments[]), а также как корневой объект методов вложений и удаления файлов.

6.1. Базовая структура

ПолеТипОписание
idintegerИдентификатор вложения
namestringИмя файла
sizeintegerРазмер в байтах
created_atstring (date-time)Дата загрузки
uuidstringУникальный идентификатор файла
browser_download_urlstringПрямая ссылка на скачивание

6.2. Вариант «asset» (в задаче assets[])

Дополнительно содержит поле download_count (integer) — количество скачиваний.

7. SubIssuesSummary (Сводка по подзадачам)

Появляется в объекте задачи, у которой есть подзадачи (parent), а также в ответах методов /sub_issues.

ПолеТипОписание
totalintegerОбщее количество дочерних задач
completedintegerКоличество завершенных дочерних задач
percent_completedintegerПроцент выполненных задач

Поле возвращается только для задач. Для запросов на слияние это поле не добавляется.

8. RepositoryRef (ветки base и head в PR)

Представляет пару «ветка + репозиторий» для целевой (base) и исходной (head) ветки запроса на слияние.

ПолеТипОписание
labelstringМетка в формате owner:ref
refstringИмя ветки
shastringSHA последнего коммита в ветке
repo_idintegerИдентификатор репозитория
repoobjectОбъект репозитория

9. Branch и BranchCommit (Ветка и коммит ветки)

Используется в массиве development.branches (связанная разработка).

9.1. Branch (Ветка)

ПолеТипОписание
namestringИмя ветки
commitobjectСсылка на коммит (см. ниже)
protectedbooleanЗащищена ли ветка
repositoryobjectРепозиторий ветки

9.2. BranchCommit

ПолеТипОписание
urlstringAPI-ссылка на коммит
shastringSHA коммита
html_urlstringСсылка на просмотр коммита
createdstring (date-time)Дата создания

10. Development (Связанная разработка)

Возвращается в объекте задачи (поле development) и как корневой объект методов /issues/{issue_number}/development.

ПолеТипОписание
pullsarrayМассив связанных запросов на слияние (объекты PR)
branchesarrayМассив связанных веток (объекты Branch)

В кратких ответах методов привязки (POST/DELETE) массив pulls может приводиться сокращенно (только number и/или title), а branches — только name, owner_name, repo_name.

11. Объекты Git-коммита (CommitMeta, GitUser, Tree)

Вложенная часть объекта Commit.

11.1. CommitMeta (поле commit)

ПолеТипОписание
authorobjectАвтор из Git-коммита (name, email, date)
committerobjectКоммиттер из Git-коммита (name, email, date)
messagestringСообщение коммита
treeobjectДерево Git (sha, url, created)
urlstringAPI-ссылка

commit.author/commit.committer — метаданные, указанные в самом Git-коммите (имя и email). Могут отличаться от объектов author/committer верхнего уровня.

11.2. GitUser (автор/коммиттер внутри commit)

ПолеТипОписание
namestringИмя
emailstringEmail
datestring (date-time)Дата

11.3. Tree (дерево)

ПолеТипОписание
shastringSHA дерева
urlstringAPI-ссылка
createdstring (date-time)Дата создания

12. Commit (Коммит)

Корневой объект массива в /pulls/{pull_number}/commits.

ПолеТипОписание
shastringSHA коммита
commitobjectМетаданные коммита
commit.authorobjectАвтор из Git
commit.committerobjectКоммиттер из Git
commit.messagestringСообщение
commit.treeobjectДерево Git
authorobject / nullПользователь-автор в GitVerse (по email); null, если не найден
committerobject / nullПользователь-коммиттер в GitVerse
parentsarrayСписок родительских коммитов (sha, url, html_url)
html_urlstringВеб-ссылка на коммит
urlstringAPI-ссылка
createdstring (date-time)Дата создания
branchstringВетка (при наличии)
filesarrayИзмененные файлы (объекты File)
statsobjectСтатистика (additions, deletions, total)
verificationobjectПроверка подписи (verified, reason, signature, payload, verified_at)

13. File (Измененный файл)

Корневой объект массива /pulls/{pull_number}/files и вложенный элемент commit.files.

ПолеТипОписание
filenamestringПуть к файлу
previous_filenamestring / nullПрежний путь (для renamed)
statusstringСтатус: added, modified, removed, renamed
additionsintegerДобавлено строк
deletionsintegerУдалено строк
changesintegerВсего изменено строк (additions + deletions)
blob_urlstringСсылка на просмотр файла
raw_urlstringПрямая ссылка на содержимое
contents_urlstringAPI-ссылка на содержимое
shastringSHA файла
patchstringОтличия в формате unified diff (может отсутствовать для бинарных)

14. Issue (Задача)

Корневой объект методов работы с задачами (/issues, /issues/{issue_number}, POST /issues, /parent, /sub_issues). Несколько составных полей переиспользуют описанные выше объекты.

Поля state_reason, pinned_comment, active_lock_reason, closed_by, author_association, draft, body_html, body_text, reactions, issue_dependencies_summary, issue_field_values в ответе не возвращаются.

ПолеТипОписание
idintegerУникальный идентификатор задачи
node_idstringГлобальный ID узла (всегда null)
urlstringAPI-ссылка на задачу
repository_urlstringAPI-ссылка на репозиторий
labels_urlstringURL-шаблон меток (.../labels{/name})
comments_urlstringURL комментариев
events_urlstring / nullURL событий (всегда null)
html_urlstringСсылка в веб-интерфейсе
numberintegerПорядковый номер задачи в репозитории
statestringСостояние: open (Открыто/Запланировано/В работе) или closed (Готово)
titlestringЗаголовок
bodystring / nullСодержимое (Markdown)
userobjectАвтор
original_authorstringИсходный автор
original_author_idintegerID исходного автора
refstringСсылка
assetsarrayВложения-ассеты
attachmentsarrayВложения
labelsarrayМетки
milestoneobject / nullВеха
assigneeobject / nullИсполнитель
assigneesarrayИсполнители
typeobject / nullТип задачи
lockedbooleanЗаблокирована ли
commentsintegerКоличество комментариев
created_atstring (date-time)Дата создания (RFC 3339)
updated_atstring (date-time)Дата обновления
closed_atstring (date-time) / nullДата закрытия
due_datestring / nullКонтрольный срок
timeline_urlstringURL таймлайна
pull_requestobject / nullМетаданные, если это PR
draftbooleanЯвляется ли черновиком (для задач всегда false)
repositoryobjectРепозиторий
developmentobjectСвязанная разработка
sub_issues_summaryobjectСводка по подзадачам (только для задач)
parent_issue_urlstring / nullURL родительской задачи (для подзадач)

15. PullRequest (Запрос на слияние)

Корневой объект методов /pulls, /pulls/{pull_number}, POST /pulls, PATCH /pulls/{number}, а также вложенный элемент development.pulls.

ПолеТипОписание
idintegerУникальный идентификатор PR
numberintegerНомер PR в репозитории
statestringСостояние: open, closed
titlestringЗаголовок
bodystringОписание
userobjectАвтор
html_urlstringСсылка в веб-интерфейсе
urlstringAPI-ссылка
diff_urlstringСсылка на diff
patch_urlstringСсылка на patch
created_atstring (date-time)Дата создания
updated_atstring (date-time)Дата обновления
closed_atstring / nullДата закрытия
merged_atstring / nullДата слияния
mergedbooleanСлит ли
mergeablebooleanМожно ли слить без конфликтов
merge_commit_shastring / nullSHA коммита слияния
merged_byobject / nullКто слил
is_draft / draftbooleanЯвляется ли черновиком
lockedbooleanЗаблокирован ли от комментариев
maintainer_can_modifybooleanМогут ли мейнтейнеры менять ветку автора
commentsintegerКоличество комментариев
review_commentsintegerКоличество ревью-комментариев
additionsintegerДобавлено строк
deletionsintegerУдалено строк
changed_filesintegerИзменено файлов
labelsarrayМетки
assigneeobject / nullИсполнитель
assigneesarrayИсполнители
milestoneobject / nullВеха (обычно null; привязывается к задачам)
requested_reviewersarrayЗапрошенные ревьюеры
requested_teamsarrayЗапрошенные команды
baseobjectЦелевая ветка
headobjectИсходная ветка

16. IssueComment (Комментарий)

Корневой объект методов комментариев к задачам/PR (/issues/{n}/comments, /issues/comments/{id}, POST/PATCH комментариев).

ПолеТипОписание
idintegerИдентификатор комментария
node_idstring / nullГлобальный ID узла (всегда null)
urlstringAPI-ссылка на комментарий
html_urlstringСсылка в веб-интерфейсе
bodystringТекст (Markdown)
body_textstringТекст без форматирования
body_htmlstringТекст в HTML
userobject / nullАвтор
attachmentsarrayВложения
created_atstring (date-time)Дата создания
updated_atstring (date-time)Дата обновления
issue_urlstringAPI-ссылка на задачу/PR
author_associationstringРоль автора: OWNER, MEMBER, CONTRIBUTOR, NONE

В ряде ответов встречается дополнительное поле reactions (обобщенная статистика реакций на комментарий). Поля body_text, body_html, author_association, performed_via_github_app, pin могут не возвращаться в зависимости от метода.

17. ReviewComment (Инлайн-комментарий к PR)

Корневой объект метода POST /pulls/{pull_number}/comments (комментарий к файлу/строке в diff).

ПолеТипОписание
idintegerИдентификатор комментария
bodystringТекст
commit_idstringSHA коммита, к которому относится комментарий
pathstringПуть к файлу
positionintegerПозиция в diff
original_positionintegerИсходная позиция
lineintegerНомер строки
sidestringСторона diff
diff_hunkstringФрагмент diff
html_urlstringСсылка в веб-интерфейсе
pull_request_urlstringСсылка на PR
pull_request_review_idintegerID ревью, в рамках которого создан комментарий
in_reply_to_idinteger / nullID комментария, ответом на который он является
original_commit_idstringSHA исходного коммита
userobjectАвтор
resolverobject / nullПользователь, закрывший (резолвнувший) комментарий
created_atstring (date-time)Дата создания
updated_atstring (date-time)Дата обновления

18. Reaction (Реакция)

Корневой объект методов реакций (POST /issues/{n}/reactions, POST .../comments/{id}/reactions).

ПолеТипОписание
idintegerИдентификатор реакции
contentstringТип реакции (например, emoji-код)
userobjectПользователь, поставивший реакцию
created_atstring (date-time)Дата создания

19. TimelineEvent (Событие таймлайна)

Корневой объект массива /issues/{issue_number}/timeline. Набор заполненных полей зависит от type события.

ПолеТипОписание
idintegerИдентификатор события
typestringТип события (comment, change_title, label, assigned, referenced и др.)
html_urlstringСсылка на событие
pull_request_urlstringСсылка на PR (для связанных событий)
issue_urlstringСсылка на задачу
userobjectИнициатор события
bodystringТекст события
created_atstring (date-time)Дата создания
updated_atstring (date-time)Дата обновления
old_project_id, project_idintegerИдентификаторы проекта
old_milestone, milestoneobject / nullВеха до/после
tracked_timestring / nullЗатраченное время
old_title, new_titlestringСтарый/новый заголовок
old_ref, new_refstringСтарая/новая ссылка
ref_issueobject / nullСвязанная задача
ref_commentobject / nullСвязанный комментарий
ref_actionstringДействие ссылки (none и др.)
ref_commit_shastringSHA коммита
review_idintegerИдентификатор ревью
labelobject / nullМетка
assigneeobject / nullИсполнитель
assignee_teamobject / nullКоманда-исполнитель
removed_assigneebooleanБыл ли исполнитель снят
resolve_doerobject / nullКто закрыл
dependent_issueobject / nullЗависимая задача

20. Review (Ревью)

Корневой объект методов ревью (/pulls/{n}/reviews, POST .../reviews, POST .../reviews/{id}/events).

ПолеТипОписание
idintegerИдентификатор ревью
statestringСостояние: COMMENTED, APPROVED, CHANGES_REQUESTED и др.
bodystringТекст ревью
userobjectАвтор
commit_idstringSHA коммита, к которому относится ревью
comments_countintegerКоличество комментариев в ревью
submitted_atstring (date-time)Дата отправки ревью
updated_atstring (date-time)Дата обновления
html_urlstringСсылка в веб-интерфейсе
pull_request_urlstringСсылка на PR
dismissedbooleanОтклонено ли
stalebooleanУстарело ли
officialbooleanОфициальное ли
teamobject / nullКоманда

21. Team и Organization (Команда и Организация)

Используются в поле requested_teams объекта PR.

21.1. Team (Команда)

ПолеТипОписание
idintegerИдентификатор команды
namestringНазвание
slugstringSlug команды
descriptionstringОписание
html_urlstringСсылка
members_urlstringСсылка на участников
members_countintegerКоличество участников
repos_countintegerКоличество репозиториев
permissionstringПраво
privacystringПриватность
can_create_org_repobooleanМожет ли создавать репозитории организации
includes_all_repositoriesbooleanВключает все репозитории
notification_settingstringНастройка уведомлений
organizationobjectОрганизация (см. ниже)

21.2. Organization (краткая)

ПолеТипОписание
idintegerИдентификатор
loginstringЛогин
avatar_urlstringАватар
html_urlstringСсылка
typestringТип (Organization)

22. Project (Проект)

Корневой объект методов работы с проектами (GET/POST /repos/{owner}/{repo}/projects, GET/PATCH /repos/{owner}/{repo}/projects/{project_id}); в ответе списка — элемент массива.

ПолеТипОписание
idintegerУникальный идентификатор проекта
titlestringНазвание проекта
descriptionstringОписание проекта
privatebooleanФлаг приватности проекта (true — приватный, false — публичный)
statestringСостояние проекта (open, closed)
created_atstring (date-time)Дата создания проекта
updated_atstring (date-time)Дата последнего обновления
closed_atstring (date-time) / nullДата закрытия проекта (если открыт — null)
columnsarrayСписок колонок проекта (массив объектов ProjectColumn)

23. ProjectColumn (Колонка проекта)

Появляется как корневой объект методов работы с колонками (POST/PATCH /repos/{owner}/{repo}/projects/{project_id}/columns/...) и как вложенный columns[] в объекте Project.

ПолеТипОписание
idintegerУникальный идентификатор колонки
titlestringНазвание колонки
colorstringЦвет колонки в формате HEX (например, #0969DA)
defaultbooleanЯвляется ли колонка колонкой по умолчанию
sortingintegerПорядковый номер колонки для сортировки
created_atstring (date-time)Дата создания колонки
updated_atstring (date-time)Дата последнего обновления колонки

24. Объекты массовых операций с задачами

Используются в ответах методов POST /repos/{owner}/{repo}/issues/bulk/update, DELETE /repos/{owner}/{repo}/issues/bulk/delete и POST /repos/{owner}/{repo}/issues/bulk/values.

24.1. IssueBulkSummary (Краткая информация о задаче)

ПолеТипОписание
idintegerВнутренний идентификатор задачи
numberintegerНомер задачи в репозитории
titlestringНазвание задачи

24.2. IssueBulkFieldError (Ошибка обработки поля)

ПолеТипОписание
fieldstringПоле, которое не удалось обработать
messagestringОписание ошибки (читаемое человеком)
reasonstringПричина ошибки (читаемая машиной)

24.3. IssueBulkFailure (Необработанная задача)

ПолеТипОписание
issueobjectКраткая информация о задаче, которую не удалось полностью обработать (см. IssueBulkSummary)
errorsarrayСписок ошибок по полям задачи (массив объектов IssueBulkFieldError)

24.4. IssueBulkResult (Результат массового обновления/удаления)

ПолеТипОписание
dataarrayСписок задач, при обработке которых возникли ошибки (массив объектов IssueBulkFailure). Если ошибок нет — пустой массив

24.5. IssueBulkValues (Значения полей выбранных задач)

ПолеТипОписание
assigneesarrayУникальные исполнители выбранных задач (массив объектов User)
due_datesarrayУникальные контрольные сроки выбранных задач (массив строк)
issue_typesarrayУникальные типы задач выбранных задач (массив объектов IssueType)
labelsarrayУникальные метки выбранных задач (массив объектов Label)
milestonesarrayУникальные вехи выбранных задач (массив объектов Milestone)
projectsarrayУникальные проекты выбранных задач (массив объектов Project)
statesarrayУникальные состояния выбранных задач (массив строк)
has_empty_assigneesbooleantrue, если хотя бы одна выбранная задача без исполнителей
has_empty_labelsbooleantrue, если хотя бы одна выбранная задача без меток
has_empty_milestonesbooleantrue, если хотя бы одна выбранная задача без вехи
has_empty_projectsbooleantrue, если хотя бы одна выбранная задача не привязана ни к одному проекту