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

Код для деплоя берётся только через подключённый 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 платформа не подключает, подробности - в разделе Границы платформы.

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

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

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

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 выключает воркспейс за неактивность и перестаёт его показывать: включить воркспейс обратно может только его владелец.

Что делать дальше с выбранным репозиторием, разобрано в разделе Источники кода.

Автодеплой

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

Порядок шагов, события вебхука и условия, при которых push заводит версию, описаны в разделе Автодеплой по push.

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

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

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

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

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

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

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

Отключение

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

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

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

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

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

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

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

Что дальше

• Источники кода - репозиторий, архив и образ
• Автодеплой по push - вебхук и условия деплоя по push
• Сборка без Dockerfile - что платформа делает с кодом после клона
• Лимиты и квоты - сколько подключений можно держать
• Границы платформы - что платформа не подключает