Подключение к GitLab

Подключение вашей учетной записи GitLab к dbt Cloud обеспечивает удобство и дополнительный уровень безопасности для dbt Cloud:

• Импортируйте новые репозитории GitLab несколькими щелчками мыши во время настройки проекта dbt Cloud.
• Клонируйте репозитории, используя HTTPS вместо SSH.
• Переносите разрешения пользователей GitLab в dbt Cloud или в git-действия dbt Cloud CLI.
• Запускайте сборки непрерывной интеграции при открытии запросов на слияние в GitLab.
  • GitLab автоматически регистрирует вебхук в вашем репозитории GitLab для обеспечения бесшовной интеграции с dbt Cloud.

Подключение вашего аккаунта GitLab к dbt обеспечивает удобство и дополнительный уровень безопасности для dbt:

• Импортируйте новые репозитории GitLab в пару кликов во время настройки проекта в dbt.
• Клонируйте репозитории по HTTPS вместо SSH.
• Передавайте пользовательские права GitLab в dbt или в git‑действия CLI dbt.
• Запускайте сборки Continuous integration при открытии merge request’ов в GitLab.

к сведению

При настройке репозитория в dbt GitLab автоматически:

• Регистрирует webhook, который запускает задания пайплайна в dbt.
• Создаёт project access token в вашем репозитории GitLab, который отправляет статус выполнения задания обратно в GitLab с использованием API dbt для CI‑заданий. dbt автоматически обновляет этот токен за вас.

Требуется аккаунт GitLab Premium или Ultimate.

В зависимости от вашего плана используйте следующие инструкции для интеграции GitLab с dbt:

• Для планов Developer или Starter ознакомьтесь с этими инструкциями.
• Для планов Enterprise или Enterprise+ перейдите к этим инструкциям.

Для планов dbt Developer и Starter

Прежде чем вы сможете работать с репозиториями GitLab в dbt, необходимо подключить ваш аккаунт GitLab к пользовательскому профилю. Это позволяет dbt аутентифицировать ваши действия при взаимодействии с Git‑репозиториями. Перед подключением аккаунта обязательно ознакомьтесь с ограничениями планов Team и Developer.

Чтобы подключить аккаунт GitLab:

1. В dbt нажмите на имя вашего аккаунта в левом боковом меню и выберите Account settings.
2. В разделе Your profile выберите Personal profile.
3. Прокрутите страницу вниз до раздела Linked accounts.
4. Нажмите Link справа от вашего аккаунта GitLab.

Когда вы нажмете Связать, вы будете перенаправлены в GitLab и вам будет предложено войти в свою учетную запись. Затем GitLab запросит ваше явное разрешение:

Экран авторизации GitLab

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

После подтверждения вы будете перенаправлены обратно в dbt, где увидите, что ваш аккаунт был связан с вашим профилем.

Требования и ограничения

Тарифы dbt Team и Developer используют один GitLab deploy token, который создаётся первым пользователем, подключившим репозиторий. Это означает, что:

• Все репозитории, к которым пользователи получают доступ из dbt platform, должны принадлежать группе GitLab.
• Все Git-операции (например, коммиты и push’и) из Studio IDE отображаются как выполненные от имени одного и того же deploy token.
• Правила push в GitLab могут отклонять push’и, выполненные через dbt, особенно когда несколько пользователей делают коммиты с использованием одного deploy token.

Для поддержки более сложных Git‑процессов и корректной работы с коммитами от нескольких пользователей рекомендуется перейти на тариф Enterprise, который предоставляет более гибкие стратегии аутентификации Git.

Для тарифов dbt Enterprise

Клиенты dbt Enterprise и Enterprise+ получают дополнительное преимущество — возможность использовать собственное OAuth‑приложение GitLab в dbt. Этот уровень обеспечивает повышенную безопасность, поскольку dbt будет:

• Принудительно применять авторизацию пользователей через OAuth.
• Передавать пользовательские права доступа к репозиториям GitLab (чтение / запись) в dbt или в Git‑действия CLI dbt.

Чтобы подключить GitLab в dbt, администратор аккаунта GitLab должен:

1. Настроить OAuth‑приложение GitLab.
2. Добавить приложение GitLab в dbt.

После выполнения этих шагов администратором, разработчикам dbt необходимо:

1. Лично пройти аутентификацию в GitLab из dbt.

В GitLab перейдите в настройки вашей группы и выберите Приложения. Здесь вы увидите форму для создания нового приложения.

Настройка OAuth‑приложения GitLab

Мы рекомендуем, чтобы перед настройкой проекта в dbt администратор аккаунта GitLab создал OAuth‑приложение в GitLab для использования в dbt.

В GitLab при создании вашего группового приложения введите следующее:

Поле	Значение
Название	dbt
Redirect URI	https://YOUR_ACCESS_URL/complete/gitlab
Конфиденциальное	✅
Области доступа (Scopes)	✅ api

Loading table...

Замените YOUR_ACCESS_URL на соответствующий URL доступа для вашего региона и плана.

Форма приложения в GitLab должна выглядеть следующим образом после заполнения:

Форма группового приложения GitLab

Нажмите Сохранить приложение в GitLab, и GitLab сгенерирует ID приложения и Секрет. Эти значения будут доступны даже если вы закроете экран приложения, так что это не единственный шанс их сохранить.

Если вы являетесь клиентом Business Critical, использующим ограничения по IP, убедитесь, что вы добавили соответствующие CIDR GitLab в ваши правила ограничения IP, иначе подключение к GitLab не удастся.

Добавление OAuth‑приложения GitLab в dbt

После того как вы создали приложение GitLab, необходимо указать информацию о нём в dbt. В dbt администраторы аккаунта должны перейти в Account Settings, нажать на вкладку Integrations и раскрыть раздел GitLab.

Navigating to the GitLab Integration in dbt

В dbt введите следующие значения:

Поле	Значение
Экземпляр GitLab	https://gitlab.com
ID приложения	скопируйте значение из приложения GitLab
Секрет	скопируйте значение из приложения GitLab

Loading table...

Обратите внимание, если у вас есть специальная хостинговая версия GitLab, измените Экземпляр GitLab, чтобы использовать предоставленное для вашей организации имя хоста, например https://gitlab.yourgreatcompany.com/.

После заполнения формы в dbt нажмите Save.

Затем вы будете перенаправлены в GitLab и вам будет предложено войти в свою учетную запись. GitLab запросит ваше явное разрешение:

Экран авторизации GitLab

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

Персональная аутентификация с GitLab

Разработчики dbt на тарифных планах Enterprise или Enterprise+ должны каждый отдельно подключить свои профили GitLab к dbt, поскольку права чтения и записи в репозиторий dbt для каждого разработчика проверяются в Studio IDE или CLI dbt.

Чтобы подключить личную учетную запись GitLab:

1. В dbt нажмите на название вашей учетной записи в меню слева и выберите Account settings.

2. Выберите Личный профиль в разделе Ваш профиль.

3. Прокрутите вниз до Связанные учетные записи.

Если ваша учетная запись GitLab не подключена, вы увидите сообщение «No connected account». Выберите Link, чтобы начать процесс настройки. Вы будете перенаправлены в GitLab, где потребуется авторизовать dbt на экране предоставления доступа.

Authorizing the dbt app for developers

После подтверждения авторизации вы будете перенаправлены обратно в dbt, и там вы должны увидеть подключенную учетную запись. Теперь вы готовы начать разработку в Studio IDE или с помощью CLI dbt.

Устранение неполадок

Невозможно запустить задачу CI с GitLab

Когда вы подключаете dbt к репозиторию GitLab, GitLab автоматически регистрирует webhook в фоновом режиме — его можно увидеть в настройках репозитория. Этот webhook также используется для запуска CI jobs при отправке изменений (push) в репозиторий.

Если вы не можете запустить задачу CI, это обычно указывает на то, что регистрация вебхука отсутствует или неверна.

Чтобы решить эту проблему, перейдите в настройки репозитория в GitLab и просмотрите регистрации вебхуков, перейдя в GitLab --> Settings --> Webhooks.

Некоторые моменты, которые стоит проверить:

• Регистрация вебхука включена в GitLab.
• Регистрация вебхука настроена с правильным URL и секретом.

Если проблема все еще сохраняется, свяжитесь с нашей службой поддержки по адресу support@getdbt.com, и мы будем рады помочь!

Ошибки при импорте репозитория при настройке проекта dbt

Если вы не видите свой репозиторий в списке, проверьте следующее:

• Ваш репозиторий находится в группе GitLab, к которой у вас есть доступ. dbt не читает репозитории, связанные с отдельным пользователем.

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

• Вы являетесь мейнтейнером этого репозитория. Только пользователи с правами мейнтейнера могут настраивать подключения к репозиторию.

Если вы импортировали репозиторий с помощью нативной интеграции dbt с GitLab, вы сможете увидеть, что в стратегии клонирования используется deploy_token. Если же используется SSH-ключ, это означает, что репозиторий был настроен не через нативную интеграцию с GitLab, а с помощью общего варианта клонирования git. В этом случае репозиторий необходимо переподключить, чтобы получить преимущества, описанные выше.

Как исправить мой файл .gitignore?

Файл .gitignore определяет, какие файлы git должен намеренно игнорировать или не отслеживать. dbt помечает неотслеживаемые файлы в панели проводника проекта, отображая имя файла или папки курсивом.

Если вы сталкиваетесь с такими проблемами, как невозможность откатить изменения, переключиться на существующую или создать новую ветку, либо если после коммита в Studio IDE вас не приглашают открыть pull request — это обычно указывает на проблему с файлом .gitignore. Файл может отсутствовать или в нём нет обязательных записей, необходимых для корректной работы dbt.

В следующих разделах описано, как исправить файл .gitignore в:

 Fix in the Studio IDE

Чтобы решить проблемы с вашим файлом gitignore, добавление правильных записей не удалит автоматически (или "не будет отслеживать") файлы или папки, которые уже отслеживаются git. Обновленный gitignore будет только предотвращать отслеживание новых файлов или папок. Поэтому вам нужно сначала исправить файл gitignore, а затем выполнить некоторые дополнительные операции git, чтобы перестать отслеживать любые неправильные файлы или папки.

1. Запустите Studio IDE в проекте, который вы исправляете, выбрав Develop в меню.
2. В File Explorer проверьте, существует ли файл .gitignore в корне папки вашего dbt‑проекта. Если его нет, создайте новый файл.
3. Откройте новый или существующий файл .gitignore и добавьте следующее:

# ✅ Правильно 
target/
dbt_packages/
logs/
# устаревшее -- переименовано в dbt_packages в dbt v1
dbt_modules/

• Примечание — Вы можете разместить эти строки в любом месте файла, главное, чтобы они были на отдельных строках. Показанные строки являются шаблонами, которые включат все вложенные файлы и папки. Избегайте добавления завершающего '*' к строкам, например, target/*.

Для получения дополнительной информации о синтаксисе gitignore обратитесь к документации Git.

4. Сохраните изменения, но не коммитьте.
5. Перезапустите IDE, нажав на три точки рядом с кнопкой IDE Status в нижнем правом углу экрана IDE и выберите Restart IDE.

Перезапустите IDE, нажав на три точки в правом нижнем углу, или нажмите на строку состояния

6. После перезапуска Studio IDE откройте File Catalog и удалите следующие файлы или папки (если они существуют). Данные при этом не будут потеряны:

   • target, dbt_modules, dbt_packages, logs

7. Сохраните изменения, затем выполните Commit and sync.

8. Перезапустите Studio IDE ещё раз, используя ту же процедуру, что и в шаге 5.

9. После перезапуска Studio IDE воспользуйтесь кнопкой Create a pull request (PR) в меню Version Control, чтобы начать процесс интеграции изменений.

10. Когда сайт git‑провайдера откроется на странице с новым PR, выполните необходимые шаги, чтобы завершить и смержить PR в основную ветку этого репозитория.

    • Примечание — Основная ветка может также называться 'master', 'dev', 'qa', 'prod' или как-то иначе в зависимости от организационных соглашений о наименовании. Цель состоит в том, чтобы слить эти изменения в корневую ветку, от которой создаются все другие ветки разработки.

11. Вернитесь в Studio IDE и с помощью кнопки Change Branch переключитесь на основную ветку проекта (main).

12. После смены ветки нажмите кнопку Pull from remote, чтобы подтянуть все изменения.

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

Проект dbt на основной ветке с правильно настроенными папками gitignore (выделены курсивом).

 Исправить в Git‑провайдере

Иногда необходимо использовать веб-интерфейс git-провайдера, чтобы исправить поврежденный файл .gitignore. Хотя конкретные шаги могут различаться у разных провайдеров, общий процесс остается тем же.

Существует два варианта для этого подхода: редактирование основной ветки напрямую, если это разрешено, или создание pull request для внесения изменений, если это требуется:

Редактировать в основной ветке

Если разрешения позволяют, можно редактировать .gitignore напрямую в основной ветке вашего репозитория. Вот следующие шаги:

1. Перейдите в веб-интерфейс вашего репозитория.
2. Переключитесь на основную ветку и корневую директорию вашего проекта dbt.
3. Найдите файл .gitignore. Создайте пустой, если он не существует.
4. Отредактируйте файл в веб-интерфейсе, добавив следующие записи:

target/
dbt_packages/
logs/
# устаревшее -- переименовано в dbt_packages в dbt v1
dbt_modules/

5. Коммитьте (сохраните) файл.
6. Удалите следующие папки из корня проекта dbt, если они существуют. Данные или код не будут потеряны:
   • target, dbt_modules, dbt_packages, logs
7. Зафиксируйте (commit) удаления в ветке main.
8. Переключитесь в Studio IDE и откройте проект, который вы исправляете.
9. Выполните откат репозитория к удалённому состоянию в IDE, нажав на три точки рядом с кнопкой IDE Status в правом нижнем углу экрана IDE, затем выберите Rollback to remote.
   • Примечание — Rollback to remote сбрасывает ваш репозиторий к более раннему клону из удалённого репозитория. Все сохранённые, но не закоммиченные изменения будут потеряны, поэтому обязательно скопируйте любой изменённый код, который вы хотите сохранить, во временное место за пределами dbt.
10. После отката к удалённому состоянию откройте файл .gitignore в ветке, с которой вы работаете. Если новые изменения в нём отсутствуют, вам нужно будет влить (merge) последние коммиты из ветки main в вашу рабочую ветку.
11. Перейдите в File Explorer, чтобы убедиться, что файл .gitignore содержит корректные записи, и проверьте, что неотслеживаемые файлы/папки, указанные в .gitignore, отображаются курсивом.
12. Отличная работа 🎉! Вы корректно настроили .gitignore и можете продолжать разработку!

Невозможно редактировать основную ветку

Если вы не можете редактировать .gitignore напрямую в основной ветке вашего репозитория, выполните следующие шаги:

1. Перейдите в веб-интерфейс вашего репозитория.
2. Переключитесь на существующую ветку разработки или создайте новую ветку только для этих изменений (это часто быстрее и чище).
3. Найдите файл .gitignore. Создайте пустой, если он не существует.
4. Отредактируйте файл в веб-интерфейсе, добавив следующие записи:

target/
dbt_packages/
logs/
# устаревшее -- переименовано в dbt_packages в dbt v1
dbt_modules/

5. Коммитьте (сохраните) файл.
6. Удалите следующие папки из корня проекта dbt, если они существуют. Данные или код не будут потеряны:
   • target, dbt_modules, dbt_packages, logs
7. Зафиксируйте (сохраните) удалённые папки.
8. Откройте merge request, используя веб‑интерфейс вашего git‑провайдера. Merge request должен быть направлен на слияние изменений в ветку main, от которой создаются все ветки разработки.
9. Следуйте необходимым процедурам, чтобы ветка была одобрена и слита в main. После завершения слияния вы можете удалить ветку.
10. После завершения слияния вернитесь в Studio IDE и откройте проект, который вы исправляете.
11. Откатите репозиторий к удалённому состоянию в Studio IDE, нажав на три точки рядом с кнопкой Studio IDE Status в правом нижнем углу экрана Studio IDE, затем выберите Rollback to remote.
    • Примечание — Rollback to remote возвращает репозиторий к более раннему клону из удалённого репозитория. Все сохранённые, но не закоммиченные изменения будут потеряны, поэтому обязательно скопируйте любой изменённый код, который вы хотите сохранить, во временное место за пределами dbt.
12. После отката к удалённому состоянию откройте файл .gitignore в ветке, над которой вы работаете. Если новые изменения не включены, вам потребуется слить последние коммиты из ветки main в вашу рабочую ветку.
13. Перейдите в File Explorer, чтобы убедиться, что файл .gitignore содержит корректные записи, и проверьте, что неотслеживаемые файлы и папки, указанные в .gitignore, отображаются курсивом.
14. Отличная работа 🎉! Вы корректно настроили .gitignore и можете продолжать разработку!

Для получения дополнительной информации см. это подробное видео с дополнительными пояснениями.

Я вижу зацикленную ошибку «GitLab authentication out of date»

Если вы видите страницу с ошибкой сервера 500 и сообщением 'GitLab Authentication is out of date', это обычно означает, что deploy key в настройках репозитория в dbt и в GitLab не совпадают.

Не беспокойтесь — это текущая проблема, над которой работает команда dbt Labs, и у нас есть несколько обходных путей, которые вы можете попробовать:

Первый обходной путь

1. Отключите репозиторий от проекта в dbt.
2. Перейдите в GitLab и нажмите Settings > Repository.
3. В разделе Repository Settings удалите или отзовите активные deploy tokens и deploy keys для dbt.
4. Попробуйте повторно подключить ваш репозиторий через dbt.
5. Затем вам нужно проверить в GitLab, что новый deploy key был добавлен.
6. После подтверждения того, что ключ добавлен, обновите dbt и попробуйте снова приступить к разработке.

Второй обходной путь

1. Оставьте репозиторий в проекте как есть — не отключайте его.
2. Скопируйте deploy key, сгенерированный в dbt.
3. Перейдите в Gitlab и нажмите Settings > Repository.
4. В разделе Repository Settings вручную добавьте deploy key в репозиторий вашего Gitlab‑проекта (с установленным флажком Grant write permissions).
5. Вернитесь в dbt, обновите страницу и попробуйте продолжить разработку.

Если вы попробовали указанные выше обходные пути и все еще сталкиваетесь с этой проблемой, свяжитесь с нашей службой поддержки по адресу support@getdbt.com, и мы будем рады помочь!

Можно ли подключать самостоятельно размещённые экземпляры GitLab только через планы dbt Enterprise?

На данный момент да, это доступно только пользователям Enterprise. Это связано с тем, как необходимо настроить URL перенаправления приложения GitLab для аутентификации, который можно настроить только если вы являетесь пользователем на тарифном плане Enterprise.

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

Как мигрировать между git-провайдерами

Чтобы мигрировать от одного git-провайдера к другому, следуйте следующим шагам, чтобы избежать минимальных перебоев:

1. Вне dbt вам потребуется импортировать существующий репозиторий в нового провайдера. По умолчанию подключение репозитория в одном аккаунте не приводит к его автоматическому отключению от другого аккаунта.

   Например, если вы мигрируете с GitHub на Azure DevOps, вам нужно импортировать существующий репозиторий (GitHub) в нового провайдера Git (Azure DevOps). Подробные инструкции по выполнению этой операции смотрите в документации вашего провайдера Git (например, GitHub, GitLab, Azure DevOps).

2. Вернитесь в dbt и при необходимости настройте интеграцию с новым провайдером Git.

3. Отключите старый репозиторий в dbt, перейдя в Account Settings, затем в Projects.

4. Нажмите на ссылку Repository, затем выберите Edit и Disconnect.

   Отключите и снова подключите ваш репозиторий Git на странице настроек учетной записи dbt.

5. Нажмите Confirm Disconnect.

6. На той же странице подключите репозиторий нового провайдера Git, нажав Configure Repository.

   • Если вы используете нативную интеграцию, может потребоваться пройти OAuth-авторизацию.

7. Готово! Теперь вы подключены к новому провайдеру Git! 🎉

Примечание — в качестве совета рекомендуем обновить страницу и Studio IDE перед выполнением каких-либо действий.

Сообщение об обновлении токена GitLab

Когда вы подключаете dbt к репозиторию GitLab, GitLab автоматически в фоновом режиме создаёт project access token в вашем репозитории GitLab. Этот токен используется для отправки статуса выполнения джоб обратно в GitLab с помощью API dbt для CI‑задач.

По умолчанию project access token имеет следующий шаблон имени: dbt token for GitLab project: <project_id>. Если в вашем репозитории есть несколько токенов, ищите токен с таким шаблоном имени, чтобы определить, какой именно используется dbt.

Если вы видите сообщение «Refresh token», не переживайте — dbt автоматически обновляет этот project access token, поэтому вам не нужно вручную выполнять его ротацию.

Если после этого вы всё ещё сталкиваетесь с ошибками обновления токена, попробуйте отключить и заново подключить репозиторий в вашем проекте dbt, чтобы обновить токен.

Если у вас возникнут какие‑либо проблемы, пожалуйста, свяжитесь с командой поддержки по адресу support@getdbt.com — мы с радостью поможем!

Нашли ошибку?

Создать GitHub Issue