SXL Studio
Источники и синхронизация

Настройка GitLab

Подключение SXL Studio к GitLab: токен со scope api, путь или ID проекта, роль в проекте, форма подключения, проверка и первая синхронизация.

Плагин работает с GitLab через REST API по Personal Access Token: ставить git на компьютер не нужно. Подходят gitlab.com и собственные серверы GitLab.

Шаг 1. Создайте Personal Access Token

  1. В GitLab откройте User Settings → Access Tokens.
  2. Нажмите Add new token, задайте имя, например SXL Studio, и срок действия.
  3. Отметьте scope api. Он нужен для чтения файлов, Push и работы с ветками. Токен только со scope read_api или read_repository позволит делать Pull, но Push и создание веток не сработают.
  4. Нажмите Create personal access token и скопируйте токен: он показывается один раз.

Токены gitlab.com начинаются с glpat-. У старых и собственных серверов префикса может не быть, это нормально: плагин отметит это в отчёте проверки, а действительность токена определит GitLab при первом запросе.

Кроме личного токена подойдёт project access token или group access token со scope api, если так принято в вашей компании.

Шаг 2. Проверьте роль в проекте

Для Push у вашей учётной записи должна быть роль Developer или выше в проекте. С ролью Reporter или Guest Pull будет работать, а Push нет. Если ветка защищена правилами проекта, Push в неё могут запретить даже Developer, тогда работайте в другой ветке.

Шаг 3. Найдите путь или ID проекта

В поле Repository плагин принимает и путь проекта, и его числовой ID:

  • путь: namespace/project, для проекта в подгруппе укажите полный путь group/subgroup/project;
  • ID: число со страницы проекта Settings → General.

Шаг 4. Создайте подключение в плагине

  1. В футере плагина нажмите шестерёнку Sync settings, затем New Sync.
  2. Заполните форму:
ПолеЗначение
ProviderGitLab
NameЛюбое имя, например Design tokens
Repository (owner/repo)design-team/tokens или 12345
BranchВетка, с которой работаете, например main
Access TokenТокен из шага 1
Data Pathdata или пусто, если папки нет
Tokens Pathtokens
Enterprise URL (Optional)Только для собственного сервера: https://gitlab.company.com
  1. Нажмите Test connection. Отчёт должен показать Connection OK. Если ветка или папки названы иначе, кнопка Fix подставит найденные значения.
  2. Нажмите Save, затем Use Git, чтобы сделать подключение активным.

Все поля формы и проверки описаны на странице Подключение к репозиторию.

Шаг 5. Первая синхронизация

  1. Нажмите Pull в футере, плагин загрузит токены и данные.
  2. Измените любой токен и нажмите Push. В окне Push для GitLab есть ссылка Show format guide: некоторые проекты требуют сообщения коммитов в формате Conventional Commits, например feat(ui): add dark mode toggle. Если сервер отклонит сообщение, плагин покажет Push rejected, поправьте текст и повторите.

Дальше: Pull, Push и ветки.

Собственный сервер GitLab

  1. В поле Enterprise URL укажите адрес сервера. Путь к API плагин добавит сам.
  2. Токен создаётся на вашем сервере так же, как на gitlab.com.
  3. Если на сервере обязательна ротация токенов, обновляйте токен в форме подключения до истечения срока: просроченный токен даст ошибку 401.

Если что-то не работает

СообщениеЧто делать
GitLab authentication failed (401)Токен недействителен, истёк или отозван. Создайте новый
GitLab denied access (403)Токену не хватает scope api, либо проект ограничен. Пересоздайте токен с api
GitLab project … was not found (404)Проверьте путь проекта или ID и что токен видит этот проект. Для подгрупп нужен полный путь
Token has read-only access to this repository: Push will failРоль в проекте ниже Developer или scope только на чтение
Push rejectedСервер не принял сообщение коммита. Откройте Show format guide в окне Push и приведите сообщение к нужному формату
Protected BranchВетка защищена. Создайте другую ветку в меню футера

Полный список проверок и ошибок: Подключение к репозиторию. Если причина не ясна, откройте вкладку Diagnostics и выполните test.

См. также