Подключение к репозиторию
Как создать подключение к GitHub или GitLab в окне Synchronization settings: поля формы, проверка Test connection, кнопка Fix, активация и типичные ошибки.
Подключение хранит адрес репозитория, ветку, папки с токенами и данными и токен доступа. Подключений может быть несколько, активно одно. Все они лежат в окне Synchronization settings на вкладке Git Sync.
Вкладка Git Sync: список подключений, кнопка New Sync, статус подключения и бейдж Active.
Что подготовить
- Personal Access Token провайдера с правом читать и записывать содержимое репозитория: GitHub, GitLab. Без токена плагин может только читать публичный репозиторий GitHub, Push будет недоступен.
- Папку с токенами в репозитории, например
tokens. Если её ещё нет, плагин создаст файлы при первом Push, но проверка подключения предупредит, что папка не найдена. - Папку с данными для Database, если вы ей пользуетесь. Это необязательно.
Создать подключение
- В футере плагина нажмите шестерёнку Sync settings.
- На вкладке Git Sync нажмите New Sync.
- Заполните форму, нажмите Test connection, при необходимости Fix, затем Save.
Пустая форма New Connection: провайдер, имя, репозиторий, ветка.
Продолжение формы: токен доступа, Data Path со значением по умолчанию и Tokens Path с подсказкой.
Поля формы
| Поле | Что вписать |
|---|---|
| Provider | GitHub или GitLab |
| Name | Любое имя, оно показывается в списке и в меню футера |
| Repository (owner/repo) | Владелец и репозиторий через косую черту, например acme/design-tokens. Для GitLab допустим числовой ID проекта |
| Branch | Ветка, с которой работает плагин. По умолчанию main |
| Access Token | Personal Access Token. Значение скрыто точками, глазок показывает его |
| Data Path | Папка с файлами Database. По умолчанию data. Если в репозитории такой папки нет, очистите поле |
| Tokens Path | Папка с JSON-файлами токенов, например tokens. Без неё файлы токенов не синхронизируются |
| Figma File URL or Key (optional) | Обычно плагин определяет ключ файла сам. Заполняйте только по просьбе поддержки |
| Local Storage | Переключатель хранения тяжёлых файлов на диске через SXL Bridge. См. Local Storage |
| Enterprise URL (Optional) | Адрес GitHub Enterprise Server или собственного GitLab, например https://gitlab.example.com. Для github.com и gitlab.com оставьте пустым |
| Code folder | Только в Dev Mode: папка с исходниками для редактора .vue. В Design Mode это поле не показывается |
Пути указываются относительно корня репозитория, без косых черт в начале и в конце. Если вы случайно вставите путь с обратными косыми чертами, пробелами или невидимыми символами, форма покажет, как именно она его прочитала.
Для сохранения нужны имя, репозиторий и токен. Остальное можно заполнить позже.
Проверка подключения
Кнопка Test connection внизу формы выполняет несколько проверок и показывает вердикт Connection OK или Problems found с временем выполнения.
Отчёт Test connection: токен, пути, репозиторий, права на запись, ветка, найденные папки и служебный файл Diff-ID.
| Проверка | Что означает |
|---|---|
| auth | Токен есть и похож на токен выбранного провайдера. Здесь же плагин предупредит, если формат не распознан или токен от другого провайдера |
| paths | Как плагин прочитал ветку и пути |
| repository | Репозиторий доступен, публичный он или приватный, какая ветка по умолчанию |
| write | Есть ли право записи. Если токен только читает, Push не сработает |
| branch | Ветка найдена, сколько файлов в ней видно в указанных папках |
| roots | Папки Tokens Path и Data Path существуют и сколько в них JSON-файлов |
| diff-id | Есть ли в репозитории служебный файл Diff-ID для этого файла Figma. Если его ещё нет, он появится после первого экспорта или Push |
| fix | Плагин нашёл, что можно исправить автоматически |
Кнопка Copy report копирует отчёт целиком, токен в него не попадает.
Кнопка Fix
Если ветка или папки указаны с опечаткой, в другом регистре или с лишними символами, проверка предложит исправления и покажет кнопку Fix с их числом. Она заменяет ветку, Tokens Path, Data Path или Code folder на найденные в репозитории значения, а пустую Tokens Path заполняет папкой, которая похожа на папку токенов. Для сохранённого подключения исправления сразу сохраняются и проверка запускается заново. Для нового подключения они подставляются в форму, нажмите Save, чтобы их оставить.
Сохранить и активировать
Нажмите Save. Если активный источник сейчас другой, в футере формы будет кнопка Use Git или Set Active: она делает это подключение активным, и в футере плагина появится имя ветки. У активного подключения в списке стоит бейдж Active, а в форме надпись Active connection.
Строка подключения показывает состояние: Connected · just now или время последней проверки, Error, если последняя операция не удалась, и Not connected, если подключение ещё не проверялось.
Изменить или удалить
Нажмите на строку подключения, откроется форма Edit Connection с теми же полями.
Edit Connection: провайдер, имя, репозиторий и ветка активного подключения.
Токен скрыт, Data Path и Tokens Path с подсказками, из какой папки будут читаться файлы.
Ключ файла Figma и карточка Local Storage с включённым переключателем.
Иконка корзины в списке удаляет подключение после подтверждения. Файлы в репозитории при этом не трогаются.
Типичные ошибки
| Сообщение | Причина и что делать |
|---|---|
| GitHub returned 404 for branch … | Неверное имя репозитория или ветки, либо токен не видит этот репозиторий. Для приватного репозитория классическому токену нужен scope repo, fine-grained токену право Contents: Read и Metadata. В организациях с SAML SSO токен нужно авторизовать для организации |
| GitHub repository … is empty (HTTP 409) | В репозитории нет ни одного коммита. Создайте первый коммит, например добавьте README |
| Unrecognized GitHub token format | Токен не похож на GitHub-токен. Проверьте, что скопировали его целиком |
| Token has read-only access to this repository: Push will fail | Токену не дали право записи. Создайте новый с правом Contents: Read and write |
| GitHub rate limit exceeded | Лимит запросов API. Это не ошибка токена, подождите минуту и повторите |
| Nothing to pull: Tokens Path not set | Не указана папка токенов. Впишите её или нажмите Fix, если плагин нашёл подходящую |
| Remote repo is too large | Провайдер вернул неполный список файлов. Сузьте Tokens Path и Data Path до нужных папок |
| GitLab denied access (403) | Токену не хватает scope api, либо проект ограничен |
Если ошибка не из списка, откройте вкладку Diagnostics и выполните test: см. Диагностика.