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

Платформа dbt

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

* Импортируйте новые репозитории GitLab в пару кликов при настройке проекта dbt.
* Клонируйте репозитории по HTTPS вместо SSH.
* Применяйте права пользователей GitLab к операциям git в dbt и dbt platform CLI.
* Запускайте сборки [непрерывной интеграции](https://docs.getdbt.tech/docs/deploy/continuous-integration.md) при открытии запросов на слияние в GitLab.

к сведению

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

* Регистрирует webhook, который запускает задания пайплайна в dbt.
* Создаёт [project access token](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html) в вашем репозитории GitLab, который отправляет статус выполнения задания обратно в GitLab с использованием API dbt для CI‑заданий. dbt автоматически обновляет этот токен за вас.

У вас должна быть [учетная запись GitLab Premium или Ultimate](https://about.gitlab.com/pricing/).

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

* Для тарифных планов Developer или Starter следуйте этим [инструкциям](#for-dbt-developer-and-starter-plans).
* Для тарифных планов Enterprise или Enterprise+ следуйте этим [инструкциям](#for-the-dbt-enterprise-plans).

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

Прежде чем работать с репозиториями GitLab в dbt, необходимо подключить учетную запись GitLab к своему профилю пользователя. Это позволяет dbt аутентифицировать ваши действия при взаимодействии с репозиториями Git. Перед подключением учетной записи обязательно ознакомьтесь с [требованиями и ограничениями](#requirements-and-limitations) тарифных планов Starter и Developer.

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

1. В dbt нажмите на название своей учетной записи в меню слева и выберите **Настройки учетной записи**.
2. В разделе **Your profile** выберите **Personal profile**.
3. Перейдите в раздел **Связанные учетные записи**.
4. Нажмите **Link** справа от вашего аккаунта GitLab.
5. В GitLab войдите в систему при появлении соответствующего запроса. Когда появится запрос авторизации, выберите вариант авторизации dbt.

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

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

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

* Все репозитории, к которым пользователи обращаются из dbt platform, должны принадлежать [группе GitLab](https://docs.gitlab.com/user/group/).
* Все 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 на доступ к репозиториям (доступ на чтение/запись) к операциям git в dbt или dbt platform CLI.

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

1. [Настроить OAuth‑приложение GitLab](#setting-up-a-gitlab-oauth-application).
2. [Добавить приложение GitLab в dbt](#adding-the-gitlab-oauth-application-to-dbt).

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

1. [Лично пройти аутентификацию в GitLab](#personally-authenticating-with-gitlab) из dbt.

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

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

Более подробные сведения можно найти в [руководстве GitLab по созданию группового приложения](https://docs.gitlab.com/ee/integration/oauth_provider.html#group-owned-applications).

Чтобы создать OAuth-приложение, принадлежащее группе, в GitLab:

1. В GitLab перейдите в настройки своей группы и выберите **Приложения**.

   [![Навигация по приложениям GitLab](</img/docs/dbt-platform/connecting-gitlab/gitlab nav.gif?v=2> "Навигация по приложениям GitLab")](#)Навигация по приложениям GitLab

2. При создании группового приложения укажите следующие данные:

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

   В поле **URI перенаправления** замените `YOUR_ACCESS_URL` на [соответствующий URL доступа](https://docs.getdbt.tech/docs/platform/about-platform/access-regions-ip-addresses.md) для вашего региона и тарифного плана.

3. Нажмите **Сохранить приложение**. GitLab создаст **Идентификатор приложения** и **Секрет**. Эти значения остаются доступными даже после закрытия экрана приложения, поэтому вы можете вернуться и сохранить их позже.

Если вы используете тарифный план Business Critical с [ограничениями по IP-адресам](https://docs.getdbt.tech/docs/platform/secure/ip-restrictions.md), убедитесь, что вы добавили соответствующие диапазоны CIDR GitLab в правила ограничения по IP-адресам, иначе подключение к GitLab не удастся.

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

После создания приложения GitLab добавьте его в dbt:

1. В dbt перейдите в **Настройки учетной записи** > **Интеграции**, затем разверните раздел GitLab.

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

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

   Если вы используете самостоятельно размещенный экземпляр GitLab, укажите в поле **Экземпляр GitLab** имя хоста GitLab вашей организации (например, `https://gitlab.yourgreatcompany.com`).

3. Нажмите **Сохранить**.

4. Затем вы будете перенаправлены в GitLab и получите запрос на вход в систему.

5. Когда появится запрос авторизации, выберите вариант авторизации dbt.

После подтверждения запроса авторизации вы будете перенаправлены обратно в dbt. Теперь интеграция готова, и разработчики вашей команды могут [пройти индивидуальную аутентификацию в GitLab](#personally-authenticating-with-gitlab).

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

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

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

1. В dbt нажмите на название своей учетной записи в меню слева и выберите **Настройки учетной записи**.
2. Выберите **Личный профиль** в разделе **Ваш профиль**.
3. Перейдите в раздел **Связанные учетные записи**.
4. Если ваша учетная запись GitLab не подключена, вы увидите "Нет подключенной учетной записи". Выберите **Связать**, чтобы начать процесс настройки.
5. В GitLab войдите в систему при появлении соответствующего запроса. Когда появится запрос авторизации, выберите вариант авторизации dbt.

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

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

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

При подключении dbt к репозиторию GitLab автоматически регистрирует вебхук в фоновом режиме. Его можно увидеть в настройках репозитория. Этот вебхук также используется для запуска [заданий CI](https://docs.getdbt.tech/docs/deploy/ci-jobs.md) при отправке изменений в репозиторий.

Если вы не можете запустить задачу 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 возникают проблемы с отменой изменений, переключением на другую ветку или созданием новой либо после коммита не появляется предложение открыть пул-реквест — это обычно указывает на проблему с файлом [.gitignore](https://github.com/dbt-labs/dbt-starter-project/blob/main/.gitignore). Этот файл может отсутствовать или не содержать записей, необходимых для корректной работы dbt.

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

 Исправление в Studio IDE

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

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

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

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

Для получения дополнительной информации о синтаксисе `gitignore` обратитесь к [документации Git](https://git-scm.com/docs/gitignore).

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

[![Перезапустите IDE, нажав на три точки в правом нижнем углу или на строку состояния](/img/docs/dbt-platform/platform-ide/restart-ide.png?v=2 "Перезапустите IDE, нажав на три точки в правом нижнем углу или на строку состояния")](#)Перезапустите IDE, нажав на три точки в правом нижнем углу или на строку состояния

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

   * `target`, `dbt_modules`, `dbt_packages`, `logs`

7. Нажмите **Save**, а затем **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** переключитесь на основную ветку проекта.

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

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

[![Проект dbt в основной ветке с правильно настроенными исключениями для папок в gitignore (выделены курсивом).](/img/docs/dbt-platform/platform-ide/gitignore-italics.png?v=2 "Проект dbt в основной ветке с правильно настроенными исключениями для папок в gitignore (выделены курсивом).")](#)Проект dbt в основной ветке с правильно настроенными исключениями для папок в gitignore (выделены курсивом).

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

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

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

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

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

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

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

5. Коммитьте (сохраните) файл.
6. Удалите следующие папки из корня проекта dbt, если они существуют. Данные или код не будут потеряны:
   * `target`, `dbt_modules`, `dbt_packages`, `logs`
7. Зафиксируйте (сохраните) удаления в основной ветке.
8. Перейдите в Studio IDE и откройте проект, который вы исправляете.
9. [Восстановите репозиторий из удалённого репозитория](https://docs.getdbt.tech/docs/platform/git/version-control-basics.md#the-git-button-in-the-cloud-ide) в IDE: нажмите на три точки рядом с кнопкой **IDE Status** в правом нижнем углу экрана IDE, затем выберите **Rollback to remote**.
   * **Примечание** — Действие Rollback to remote возвращает ваш репозиторий к состоянию ранее созданного клона удалённого репозитория. Все сохранённые, но не зафиксированные изменения будут потеряны, поэтому обязательно скопируйте изменённый код, который хотите сохранить, во временное расположение за пределами dbt.
10. После восстановления из удалённого репозитория откройте файл `.gitignore` в ветке, в которой вы работаете. Если новых изменений в нём нет, вам потребуется влить последние коммиты из основной ветки в вашу рабочую ветку.
11. Перейдите в **File Explorer**, чтобы проверить, что файл `.gitignore` содержит правильные записи, и убедитесь, что неотслеживаемые файлы и папки, указанные в .gitignore, выделены *курсивом*.
12. Отличная работа 🎉! Вы правильно настроили `.gitignore` и можете продолжать разработку!

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

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

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

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

5. Коммитьте (сохраните) файл.
6. Удалите следующие папки из корня проекта dbt, если они существуют. Данные или код не будут потеряны:
   * `target`, `dbt_modules`, `dbt_packages`, `logs`
7. Зафиксируйте (сохраните в коммите) удаление папок.
8. Откройте запрос на слияние через веб-интерфейс вашего Git-провайдера. Запрос должен быть направлен на слияние изменений с веткой 'main', от которой создаются все ветки разработки.
9. Выполните необходимые процедуры, чтобы получить одобрение и слить ветку с веткой 'main'. После завершения слияния вы можете удалить ветку.
10. После завершения слияния вернитесь в Studio IDE и откройте проект, который вы исправляете.
11. [Выполните откат репозитория к состоянию удалённого репозитория](https://docs.getdbt.tech/docs/platform/git/version-control-basics.md#the-git-button-in-the-cloud-ide) в Studio IDE: нажмите на три точки рядом с кнопкой **Studio IDE Status** в правом нижнем углу экрана Studio IDE, затем выберите **Rollback to remote**.
    * **Примечание** — Действие Rollback to remote возвращает репозиторий к состоянию ранее созданной копии удалённого репозитория. Все сохранённые, но не зафиксированные в коммите изменения будут потеряны, поэтому обязательно скопируйте изменённый код, который хотите сохранить, во временное расположение за пределами dbt.
12. После отката к состоянию удалённого репозитория откройте файл `.gitignore` в ветке, над которой вы работаете. Если новые изменения отсутствуют, вам потребуется слить последние коммиты из ветки main с вашей рабочей веткой.
13. Перейдите в **File Explorer**, чтобы убедиться, что файл `.gitignore` содержит правильные записи, а неотслеживаемые файлы и папки, указанные в .gitignore, отображаются *курсивом*.
14. Отличная работа 🎉! Вы правильно настроили `.gitignore` и можете продолжать разработку!

Для получения дополнительной информации см. это [подробное видео](https://www.loom.com/share/9b3b8e2b617f41a8bad76ec7e42dd014) с дополнительными пояснениями.

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

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

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

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

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

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

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

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

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

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

Посмотрите нашу [страницу с ценами](https://www.getdbt.com/pricing/) для получения дополнительной информации или свяжитесь с нами через [контактную форму](https://www.getdbt.com/contact), чтобы обсудить условия тарифа Enterprise.

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

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

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

   Например, если вы мигрируете с GitHub на Azure DevOps, вам нужно импортировать существующий репозиторий (GitHub) в нового провайдера Git (Azure DevOps). Подробные инструкции по выполнению этой операции смотрите в документации вашего провайдера Git (например, [GitHub](https://docs.github.com/en/migrations/importing-source-code/using-github-importer/importing-a-repository-with-github-importer), [GitLab](https://docs.gitlab.com/ee/user/project/import/repo_by_url.html), [Azure DevOps](https://learn.microsoft.com/en-us/azure/devops/repos/git/import-git-repository?view=azure-devops)).

2. Вернитесь в dbt и при необходимости настройте [интеграцию с новым провайдером Git](https://docs.getdbt.tech/docs/platform/git/configure-git.md).

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

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

   [![Отключение и повторное подключение Git-репозитория на странице настроек аккаунта dbt.](/img/docs/dbt-platform/disconnect-repo.png?v=2 "Отключение и повторное подключение Git-репозитория на странице настроек аккаунта dbt.")](#)Отключение и повторное подключение Git-репозитория на странице настроек аккаунта dbt.

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

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

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

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

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

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

Когда вы подключаете dbt к репозиторию GitLab, GitLab автоматически создает в фоновом режиме [токен доступа к проекту](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html) в вашем репозитории GitLab. Он используется для отправки статуса выполнения заданий CI обратно в GitLab через API dbt.

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

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

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

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