# Подключение GitHub, GitLab и Bitbucket

> Как подключить GitHub App, токен GitLab или токен Bitbucket и выбрать репозиторий из списка, приватный или публичный.

Раздел: Деплой
Источник: https://nodbox.ru/docs/deploy/git-accounts/

---
Код для деплоя берётся только через подключённый git-аккаунт: адрес репозитория вставлять не нужно, ты выбираешь его из списка. Подключить можно GitHub, GitLab на gitlab.com и Bitbucket на bitbucket.org, а приватные и публичные репозитории выбираются одинаково.

## Что подключается и чем

| Сервис | Как выдаётся доступ | Что понадобится | Вебхук автодеплоя |
| --- | --- | --- | --- |
| GitHub | установка GitHub App в браузере | аккаунт GitHub | платформенный, настраивать нечего |
| GitLab | access token | токен с правами `read_api` и `read_repository` | заводишь сам |
| Bitbucket | API-токен Atlassian | почта Atlassian и токен с тремя правами | заводишь сам |

Подключение принадлежит тебе, а не проекту: аккаунт подключается один раз и работает во всех твоих проектах. Доступ только на чтение, писать в репозиторий платформа не может.

GitLab с собственным адресом, GitHub Enterprise и собственное GitHub App платформа не подключает, подробности - в разделе [Границы платформы](/docs/help/limitations/).

## Где подключить

В панели открой «Источники кода» и нажми «Подключить сервис». Откроется окно «Какой сервис подключить» со списком GitHub, GitLab и Bitbucket. Дальнейшие шаги зависят от сервиса.

Завести подключение можно с подтверждённой почтой. Число подключений на аккаунт ограничено: рядом с кнопкой в панели видно, сколько занято, а цифры лимита собраны в разделе [Лимиты и квоты](/docs/project/limits/). В счёт входят и подключения, которые ждут подтверждения или потеряли доступ, пока их не отключат.

## GitHub

GitHub выдаёт доступ установкой приложения nodbox, поэтому токен выпускать не нужно:

1. В окне выбери GitHub. Панель покажет кнопку «Открыть GitHub».
2. На GitHub выбери аккаунт или организацию, в которую ставится приложение, и репозитории: все или только выбранные.
3. Подтверди установку. GitHub вернёт тебя в панель, а подключение станет активным само. Окно можно не закрывать.

Ссылка на установку действует 10 минут. Если не успел, отключи подключение, которое осталось в статусе «Ждёт подтверждения», и подключи GitHub заново.

Если организация требует одобрения владельца, GitHub отправляет ему запрос, и подключение не подтверждается. Когда владелец установит приложение, подключи GitHub заново.

Платформа не хранит у себя токен GitHub. Она помнит только номер установки и выпускает доступ на час в момент обращения. Какие репозитории открыты, определяет установка: в панели у подключения написано «все репозитории» или «выбранные репозитории». Состав меняется на стороне GitHub в настройках установленного приложения, список в панели читается заново при каждом открытии, переподключать ничего не нужно.

## GitLab

GitLab подключается токеном доступа любого вида: личным, групповым или проектным. Нужны два права:

- `read_api` открывает список проектов и веток
- `read_repository` нужен, чтобы забрать код при сборке

Права выпущенному токену добавить нельзя, поэтому отметь оба сразу. Deploy token не подходит: с API GitLab он не работает, и списка проектов им не получить.

1. Выпусти токен. Личный проще всего по ссылке «Выпустить токен» рядом с полем в панели: страница GitLab откроется с уже отмеченными правами. Групповой или проектный токен выпускается в настройках группы или проекта, в разделе Access tokens.
2. В окне «Какой сервис подключить» выбери GitLab, вставь токен в поле «Токен» и нажми «Подключить».

Платформа проверяет токен сразу, не дожидаясь первого деплоя: узнаёт его владельца и пробует прочитать список проектов. Подключение появляется уже активным. Если токен не подошёл, панель говорит причину:

- токен неверный, просроченный или отозванный - нужен другой токен
- токен опознан, но выпущен без нужных прав - нужен новый токен с правами `read_api` и `read_repository`

В списке только проекты, в которых владелец токена состоит участником. Групповой токен покажет проекты своей группы, проектный - один проект.

## Bitbucket

Bitbucket подключается парой: почта учётной записи Atlassian и API-токен. У токена должны быть три права:

- `read:user:bitbucket`
- `read:workspace:bitbucket`
- `read:repository:bitbucket`

Токен без прав Bitbucket не принимает. На странице Atlassian две кнопки, и первая из них, «Create API token», выпускает как раз такой токен. Нужна «Create API token with scopes», приложение Bitbucket. App password больше не работает: Atlassian его закрыл.

1. Выпусти токен. Ссылка «Выпустить токен» рядом с полем в панели открывает страницу API-токенов Atlassian.
2. В окне выбери Bitbucket, впиши почту в поле «Почта Atlassian», токен в поле «API-токен» и нажми «Подключить».

Платформа проверяет все три права тем, что пробует их применить: читает профиль, воркспейсы и репозитории. Репозитории собираются по воркспейсам, в которых у владельца токена есть явный доступ.

## Выбор репозитория

Репозиторий выбирается при создании приложения. В панели на странице «Новое приложение» открой карточку «Откуда брать код» и вкладку «Репозиторий». Там три поля:

- «Аккаунт» - подключение, из которого берётся код
- «Репозиторий» - список с поиском по имени, у приватных стоит замок
- «Ветка» - по умолчанию подставляется главная ветка репозитория

Список платформа читает у сервиса при каждом открытии и у себя не хранит, поэтому только что созданный репозиторий появляется в нём сразу. В списке только репозитории, к которым у подключения есть доступ. Чужой публичный репозиторий не появится: сделай его форк в свой аккаунт.

Панель загружает до 500 репозиториев подключения, поиск идёт по загруженным. Если нужного не видно, сузь доступ: на GitHub выдай установке только нужные репозитории, на GitLab используй групповой или проектный токен.

Пустой список не всегда значит, что репозиториев нет. На GitHub их могли не выдать при установке, а Bitbucket выключает воркспейс за неактивность и перестаёт его показывать: включить воркспейс обратно может только его владелец.

Что делать дальше с выбранным репозиторием, разобрано в разделе [Источники кода](/docs/deploy/sources/).

## Автодеплой

На GitHub вебхук платформенный: push доходит до платформы сам. На GitLab и Bitbucket вебхук заводишь ты, потому что права на запись в репозиторий у платформы нет. Адрес и секрет вебхука показаны в панели: у подключения нажми «Настроить автодеплой» или открой меню действий и выбери «Автодеплой по push». Адрес у каждого подключения свой, а секрет окно показывает при каждом открытии.

Порядок шагов, события вебхука и условия, при которых push заводит версию, описаны в разделе [Автодеплой по push](/docs/deploy/auto-deploy/).

## Проверка доступа

Доступ у сервиса могут отозвать без участия платформы: токен истёк, приложение удалено на GitHub, изменились права. Платформа узнаёт об этом, когда проверяет доступ или читает список репозиториев. В меню действий подключения нажми «Проверить доступ»: платформа спросит сервис, обновит логин аккаунта и состав репозиториев. У рабочего подключения статус «Подключён», у потерявшего доступ - «Доступ отозван».

Сервис может ответить и иначе. Если токен опознан, но ему отказано в действии, подключение остаётся активным, а платформа говорит, что учётным данным не хватает прав. Проверь права токена и ограничения аккаунта у сервиса. Если сервис временно недоступен, статус не меняется: повтори через несколько минут.

## Пропавший доступ и замена токена

У подключения в статусе «Доступ отозван» платформа стирает токен. Деплой из такого подключения не пройдёт: платформа не сможет забрать код, а заказ новой версии получит отказ.

Токен в существующем подключении не меняется. Чтобы вернуть доступ:

1. На GitLab или Bitbucket выпусти новый токен, на GitHub ничего выпускать не нужно.
2. Отключи прежнее подключение, в том числе отозванное: один аккаунт у сервиса заводится в nodbox одним подключением, и пока старое на месте, тот же аккаунт подключить второй раз нельзя.
3. Подключи аккаунт заново.
4. Привяжи приложения к новому подключению. При создании приложения оно выбирается в поле «Аккаунт», а у готового приложения его меняет правка приложения в [API](/docs/automation/api/): поля `git_connection_id`, `repository_full_name` и `branch`.

## Отключение

В меню действий подключения выбери «Отключить» и подтверди кнопкой «Отключить». Кнопка «Оставить» закрывает окно без последствий.

После отключения:

- работающие приложения продолжают работать
- автодеплой по push останавливается
- новую версию приложение не закажет, пока его не привяжут к другому подключению, а платформа ответит, что подключение больше недоступно
- место в лимите подключений освобождается

Что остаётся у сервиса, зависит от него. На GitHub платформа сама снимает установку приложения nodbox. На GitLab и Bitbucket платформа токен не отзывает: он общий для твоих скриптов и CI, и сломать их она не вправе. Токен у платформы стирается, а на стороне сервиса отзови его сам, если он больше не нужен.

## Безопасность

- Токены GitLab и Bitbucket хранятся зашифрованными и наружу не возвращаются ни в панели, ни по API
- Токен стирается при отзыве доступа и при отключении подключения
- Секрет вебхука принадлежит платформе, а не сервису: он показан только владельцу подключения
- Управлять подключениями может только их владелец

Заводить, проверять, переименовывать и отключать подключения можно со входом через панель или `nodbox login`. Токен для агента с четырьмя правами этого не умеет, с правом читать он видит только список подключений, репозиториев и веток.

## Что дальше

- [Источники кода](/docs/deploy/sources/) - репозиторий, архив и образ
- [Автодеплой по push](/docs/deploy/auto-deploy/) - вебхук и условия деплоя по push
- [Сборка без Dockerfile](/docs/deploy/build/) - что платформа делает с кодом после клона
- [Лимиты и квоты](/docs/project/limits/) - сколько подключений можно держать
- [Границы платформы](/docs/help/limitations/) - что платформа не подключает