# Интеграция с GitHub {#github}

Git-репозитории — основа подавляющего большинства программных проектов. Мы интегрируемся с GitHub, чтобы предоставлять аналитику Tuist прямо в ваших пул-реквестах и избавлять от части настройки, например синхронизации ветки по умолчанию.

## Настройка {#setup}

Установите приложение Tuist для GitHub во вкладке `Integrations` вашей организации: ![Изображение, показывающее вкладку интеграций](/images/guides/integrations/gitforge/github/integrations.png)

Вы также можете установить приложение напрямую из GitHub. При необходимости войдите в Tuist, авторизуйте приложение GitHub, чтобы Tuist мог подтвердить ваш доступ к установке, и выберите организацию Tuist для подключения. Вы должны владеть организацией GitHub (или личным аккаунтом GitHub), куда устанавливается приложение. Доступны только организации Tuist, которыми вы управляете, и ваш личный аккаунт Tuist. Если доступен только один аккаунт, Tuist подключит его автоматически, не показывая выбор. При начале работы из Tuist организация уже выбрана, и этот шаг пропускается.

После этого вы можете добавить связь проекта между вашим репозиторием GitHub и проектом Tuist:

![Изображение, показывающее добавление связи проекта](/images/guides/integrations/gitforge/github/add-project-connection.png)

После установки приложения вы также можете связать проект без использования панели управления:

- **CLI:** `tuist project repository connect owner/name`, а также `tuist project repository disconnect` для удаления связи.
- **REST API:** методы `PUT` и `DELETE` для `/api/projects/{account_handle}/{project_handle}/vcs-connection`.
- **Model Context Protocol:** инструменты `connect_project_repository` и `disconnect_project_repository`.

Репозиторий должен быть доступен установке приложения GitHub, а проект использует ветку по умолчанию этого репозитория. Токенам аккаунта требуется область доступа `project:admin:write`.

> [!TIP]
> **Разрешённые IP-адреса**
>
> Если ваша организация GitHub использует [списки разрешённых IP-адресов](https://docs.github.com/en/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization) или ваш экземпляр GitHub находится за файрволом, обязательно добавьте исходящие IP-адреса Tuist <.localized_link href="/guides/server/network#outbound-ip-addresses"></.localized_link> в белый список, чтобы интеграция могла взаимодействовать с вашим репозиторием.

### GitHub Enterprise Server {#github-enterprise-server}

Tuist также интегрируется с самостоятельно размещёнными экземплярами GitHub Enterprise Server (GHES). На карточке интеграции с GitHub перейдите на вкладку **Enterprise server**, введите базовый URL вашего GHES (например, `https://github.example.com`) и нажмите «Install».

Поскольку приложения GitHub привязаны к одному экземпляру GitHub, Tuist не может повторно использовать своё приложение с github.com в вашем GHES. Вместо этого кнопка установки запускает [поток манифеста приложения](https://docs.github.com/en/apps/sharing-github-apps/registering-a-github-app-from-a-manifest) GitHub: GHES помогает вашему администратору зарегистрировать новое приложение Tuist на экземпляре, а затем передаёт учётные данные нового приложения обратно в Tuist. Tuist хранит эти учётные данные в зашифрованном виде для каждой установки и использует их для всех вызовов API, подписей вебхуков и ссылок на ваши репозитории.

Дополнительная настройка сервера Tuist не требуется: поток манифеста автоматически генерирует и настраивает всё необходимое.

#### Разрешения приложения и события вебхуков {#github-app-permissions}

Для комментариев к пул-реквестам и проверок размера бандла Tuist требует следующие **разрешения для репозитория**:

| Разрешение | Доступ | Используется для |
|---|---|---|
| Метаданные (`metadata`) | Только чтение | Базовые метаданные репозитория; требуются GitHub для каждого приложения |
| Пул-реквесты (`pull_requests`) | Чтение и запись | Чтение пул-реквестов, включая SHA хед-коммита, а также получение списка, публикация и обновление комментариев к пул-реквестам |
| Проверки (`checks`) | Чтение и запись | Создание и обновление запусков проверок, включая проверки прохождения/непрохождения по размеру бандла |

Tuist использует событие вебхука `check_run` для обработки действий проверки размера бандла. Поток манифеста настраивает эту подписку автоматически.

Для ручной настройки приложения на github.com с самостоятельно размещённым сервером Tuist см. <.localized_link href="/guides/server/self-host/server#platform-github-registering-the-app">руководство по самостоятельному размещению</.localized_link>.

#### Отдельные URL для браузера и API {#separate-browser-and-api-urls}

Если инженеры получают доступ к GitHub Enterprise через внутренний хостнейм, а сторонние сервисы используют внешний прокси, настройте оба адреса перед нажатием кнопки установки:

| Поле | Пример | Используется |
|---|---|---|
| **URL сервера** | `https://github.internal.company.com` | Ваш браузер, для регистрации и установки приложения, а также ссылки на GitHub из Tuist |
| **URL API** | `https://github-proxy.company.com/api/v3` | Серверы Tuist, для обмена кодом манифеста, получения токенов доступа, доступа к репозиторию, комментариев к пул-реквестам и проверок |

URL API — это полный базовый URL REST API, включая `/api/v3` или эквивалентный путь, предоставляемый вашим прокси. Tuist не добавляет `/api/v3` к явно указанному URL API. Оставьте поле пустым, если один хостнейм работает и для вашего браузера, и для Tuist; существующие подключения продолжат использовать `<Server URL>/api/v3`.

Оба адреса должны направлять запросы к **одному и тому же экземпляру GitHub Enterprise**. Вашему браузеру нужно обращаться только к URL сервера, а не к API-прокси. Серверам Tuist нужно обращаться только к URL API, а не к внутреннему хостнейму браузера.

Для внешнего прокси:

- Используйте HTTPS с сертификатом, которому доверяют серверы Tuist, и публичным DNS, разрешающимся в публичные IP-адреса. Переопределения URL API не обходят защиты Tuist от частных IP-адресов и SSRF. Переопределение должно указывать на ваш экземпляр Enterprise, а не на `github.com` или конечную точку `*.github.com`.
- Добавьте в белый список каждый <.localized_link href="/guides/server/network#outbound-ip-addresses">исходящий IP-адрес</.localized_link> Tuist.
- Перенаправляйте конечные точки REST API, которые использует Tuist, включая `POST /api/v3/app-manifests/{code}/conversions`, `POST /api/v3/app/installations/{installation_id}/access_tokens` и конечные точки API репозитория для комментариев и проверок. Это upstream-пути GitHub; переведите их, если ваш прокси предоставляет другой префикс.
- Перенаправляйте запросы к GitHub без HTTP-редиректов или интерактивной страницы входа. Tuist не следует автоматически за редиректами API Enterprise, поэтому они не могут обойти проверки публичных IP-адресов. Конечная точка конвертации манифеста должна быть доступна во время настройки, до того как у Tuist появятся учетные данные приложения. Загрузка логов GitHub Actions является исключением: Tuist следует за редиректами подписанных архивов только по HTTPS, проверяет и привязывает каждое назначение к публичному IP-адресу и не пересылает токен установки.

GitHub может возвращать ссылки пагинации, используя свой внутренний хостнейм. Tuist перебазирует ссылки от настроенного экземпляра GitHub на URL API, сохраняя префикс пути вашего прокси; ссылки на нерелевантные источники отклоняются.

Отдельно, GitHub должен иметь возможность доставлять вебхуки на `https://tuist.dev/webhooks/github` (или `/webhooks/github` на вашем самостоятельно размещённом сервере Tuist). Инженеры должны иметь возможность вернуться в Tuist для завершения обратных вызовов браузера. URL API не меняет ни одно из этих назначений.

Администраторы организации также могут изменить или очистить URL API в существующей интеграции Enterprise, используя **Сохранить URL API** в карточке интеграции. Переустановка приложения или повторное подключение проекта не требуются. Очистка восстанавливает `<Server URL>/api/v3`. При сохранении проверяется формат URL, а не подключение через прокси. Обработка вебхуков может занять до одной минуты для использования измененного адреса, так как поиски установки кэшируются; запросы, уже находящиеся в процессе выполнения, могут все еще использовать предыдущий адрес.

> [!NOTE]
> **Тариф Enterprise доступен только на хостируемом сервере Tuist**
>
> На хостируемом сервере Tuist (`https://tuist.dev`) интеграция с GitHub Enterprise Server доступна исключительно организациям на тарифе **Enterprise**. Самостоятельно размещённые развертывания Tuist могут использовать её на любом тарифе.

## Комментарии к пул-реквестам/merge-реквестам {#pull-merge-request-comments}

Приложение GitHub публикует отчет о запуске Tuist, который включает сводку по пул-реквесту, в том числе ссылки на последние <.localized_link href="/guides/features/previews/xcode#pullmerge-request-comments">превью</.localized_link> или <.localized_link href="/guides/features/selective-testing#pullmerge-request-comments">тесты</.localized_link>:

Tuist обновляет один комментарий по мере поступления результатов. Сборки Gradle отображаются отдельно для каждого корневого проекта и набора запрошенных задач; повторный запуск тех же задач заменяет предыдущий результат этого вызова. Полная история сборок остается доступной в Tuist.

Комментарии включены по умолчанию, что сохраняет отчетность для существующих интеграций. Чтобы отключить или снова включить их для проекта, откройте **Настройки проекта → Интеграции** и переключите **GitHub → Комментарии к отчетам о запусках**. У каждого проекта своя настройка; подключения репозиториев остаются под управлением в настройках организации.

Отключение комментариев не отключает выгрузку сборок или тестов, сводки заданий GitHub Actions, подключения репозиториев или другие функции интеграции с GitHub. Существующие комментарии не удаляются.

![Изображение, показывающее комментарий к пул-реквесту](/images/guides/integrations/gitforge/github/pull-request-comment.png)

> [!NOTE]
> **Требования**
>
> Комментарий публикуется только тогда, когда ваши запуски CI <.localized_link href="/guides/integrations/continuous-integration#authentication">аутентифицированы</.localized_link>.

> [!NOTE]
> **Github_ref**
>
> Если у вас есть пользовательский рабочий процесс, который запускается не коммитом пул-реквеста, а, например, комментарием GitHub, вам может потребоваться убедиться, что переменная `GITHUB_REF` установлена либо в `refs/pull/<PR_NUMBER>/merge`, либо в `refs/pull/<PR_NUMBER>/head`.
>
> Вы можете запустить соответствующую команду, например `tuist share`, с префиксом переменной окружения `GITHUB_REF`: <code v-pre>GITHUB_REF="refs/pull/${{ github.event.issue.number }}/head" tuist share</code>

## Сводка задания GitHub Actions {#github-actions-job-summary}

CLI Tuist и плагин Gradle записывают результаты тестов и сборок в [сводку задания](https://github.blog/news-insights/product-news/supercharging-github-actions-with-job-summaries/) в GitHub Actions. Сводка содержит ссылку на полный отчет в Tuist, где доступны более подробные данные, такие как нестабильные тесты и изменения размера бандла.

Для Gradle каждый успешно загруженный отчет о сборке или тесте добавляет свою собственную сводку, сохраняя другой контент, записанный такими инструментами, как `gradle/actions/setup-gradle`. Для этого требуется версия плагина, поддерживающая сводки заданий; старые версии плагина Gradle сообщают результаты только через комментарий приложения GitHub к пул-реквесту. Приложение GitHub не нужно подключать для сводок заданий, и отключение **Комментариев к отчетам о запусках** на них не влияет.

Когда доступно назначение для сводки GitHub Actions, Gradle ожидает завершения выгрузок и формирования сводок перед выходом, даже если включено `uploadInBackground`. GitHub фиксирует сводку при завершении шага рабочего процесса.

![Изображение, показывающее отчет о запуске Tuist в сводке задания GitHub Actions](/images/guides/integrations/gitforge/github/github-actions-job-summary.png)

Это особенно полезно при использовании [очередей слияния](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue). Запуск из очереди слияния не привязан к пул-реквесту, поэтому комментарий не публикуется, но сводка задания все равно отображает результаты.

> [!NOTE]
> **Требования**
>
> Для сводок заданий требуется успешная выгрузка отчета. На хостируемом сервере Tuist ваши запуски CI должны быть <.localized_link href="/guides/integrations/continuous-integration#authentication">аутентифицированы</.localized_link>. Самостоятельно размещённые экземпляры также могут принимать отчеты без учетных данных, если включена публикация отчетов с доверенной сети.