# Интеграция Baserow и GitLab: вебхуки и REST API для CI/CD

> Каждый запуск конвейера GitLab способен менять статус строки Baserow через REST API - разбираем database-токен, вебхук и правки .gitlab-ci.yml.

Source: https://opennix.org/docs/baserow/integrations/gitlab-integration/


Инженерные команды живут в GitLab, а продуктовые и операционные - в Baserow: связка строится на database-токене Baserow и персональном токене доступа GitLab, вебхуке, который дёргает пайплайн из строки таблицы, и обратном вызове REST API, которым конвейер GitLab пишет свой статус обратно в эту же строку - ниже пошаговая настройка обеих сторон и запасной низкокодовый вариант через стороннюю платформу автоматизации.

## Зачем связывать Baserow и GitLab

GitLab закрывает техническую часть - управление кодом, CI/CD-конвейеры, сборки и деплой. Baserow закрывает бизнес-часть - приоритеты спринта, клиентские обязательства, список изменений релиза, согласования и коммуникацию по запуску. Без связки между инструментами заинтересованные лица дёргают инженеров за статусами, а инженеры тратят время на ручное обновление тикетов.

Типичное применение интеграции - автоматизация учёта задач, синхронизация данных CI/CD или удобный для нетехнических пользователей интерфейс поверх данных репозитория.

## Способы интеграции

**Способ A. Низкокодовая автоматизация.** Самый частый способ синхронизации между платформами через стороннее no-code средство: триггер («новая строка в Baserow» или «новый issue в GitLab») запускает действие, которое сопоставляет данные и отправляет их в другое приложение. Для аутентификации нужен database-токен Baserow и персональный токен доступа (PAT) GitLab.

**Способ B. Нативные вебхуки.** Подходит для лёгких односторонних уведомлений без промежуточного инструмента. Из Baserow в GitLab - вебхук Baserow обращается к URL «Trigger Token» GitLab, чтобы запустить конвейер. Из GitLab в Baserow - вебхук GitLab (системный или на уровне проекта) отправляет данные события на URL вебхука Baserow.

## Типичные сценарии использования

- **Внешний учёт задач.** Нетехнические участники отправляют баг через форменное представление Baserow, которое автоматически создаёт issue в GitLab.
- **Управление релизами.** Статус деплоя отслеживается в таблице Baserow, а перевод строки в статус «Готово к деплою» запускает конвейер GitLab.
- **Учёт запусков конвейера.** Каждый успешный запуск конвейера GitLab записывается в таблицу Baserow для долгосрочной отчётности.

| Область | В GitLab | В Baserow |
|---|---|---|
| Управление релизами | Конвейеры разворачивают код в staging и production по тегам (например, `v2.4.0`) | Релиз-менеджеры планируют состав `v2.4.0`, отслеживают согласования от юристов и маркетинга, формируют список изменений |
| Реагирование на инциденты | Разработчики закрывают issue-инциденты, вызвавшие сбой в production | Команда эксплуатации ведёт в Baserow журнал инцидентов: время восстановления, анализ влияния, отчёты по итогам |
| Feature-флаги | Инженеры реализуют флаги в коде для переключения функциональности | Продуктовая команда управляет процентом раскатки в Baserow; вебхук синхронизирует поле «Процент раскатки» с конфигурацией приложения |
| Комплаенс | GitLab хранит историю коммитов и логи конвейеров | Baserow хранит формы запроса на изменение, которые требуют аудиторы, связывая конкретные коммиты GitLab с деловыми согласованиями |

## Замкнутый цикл: строка Baserow - конвейер GitLab - строка Baserow

Самый надёжный способ связать инструменты - привязать идентификатор строки Baserow к конвейеру GitLab:

1. **Запуск.** Baserow отправляет вебхук с `Row ID` в GitLab.
2. **Контекст.** GitLab принимает идентификатор и хранит его как переменную на всё время работы конвейера.
3. **Обратная связь.** По завершении конвейера (успех или ошибка) GitLab использует этот идентификатор, чтобы записать статус обратно в нужную строку Baserow.

Ниже описан именно этот мост: «слушатель» добавляется в конвейеры GitLab, а «диспетчер» - в таблицы Baserow, без замены уже существующих скриптов.

## Предварительные требования

- **GitLab:** проект с включённым CI/CD и правами Maintainer.
- **Baserow:** [database-токен (API-токен)](/docs/baserow/webhook-api/personal-api-tokens/) с правами на запись.

## Шаг 1. Настройка аутентификации

Обоим инструментам нужно право обращаться друг к другу.

1. В Baserow откройте **Settings → Database Tokens**, создайте новый токен с правами **Write** и скопируйте его.
2. В GitLab откройте **Settings → CI/CD → Variables**.
3. Добавьте переменную `BASEROW_TOKEN`.
4. Вставьте токен Baserow в качестве значения.
5. Отметьте «Mask variable», чтобы скрыть значение в логах.

## Шаг 2. Слушатель в GitLab

Добавьте job-триггер в существующий файл `.gitlab-ci.yml` - он запускается только по запросу от Baserow и оборачивает уже имеющиеся скрипты:

```yaml
baserow_trigger_job:
  stage: deploy
  image: badouralix/curl-jq
  rules:
    # Job запускается только при вызове через API (например, вебхуком Baserow)
    - if: $CI_PIPELINE_SOURCE == "trigger"
  script:
    # 1. ЧТЕНИЕ: получить Row ID, отправленный Baserow
    - export ROW_ID=$(cat $TRIGGER_PAYLOAD | jq -r '.items[0].id')

    # 2. ЗАПИСЬ: сообщить Baserow "работа началась"
    # Замените [YOUR_TABLE_ID] на идентификатор таблицы из её URL
    - |
      curl -X PATCH \
        -H "Authorization: Token ${BASEROW_TOKEN}" \
        -H "Content-Type: application/json" \
        -d '{"Status": "In Progress", "GitLab Job ID": "'"$CI_PIPELINE_ID"'"}' \
        "https://api.baserow.io/api/database/rows/table/[YOUR_TABLE_ID]/${ROW_ID}/?user_field_names=true"

    # 3. ВЫПОЛНЕНИЕ: здесь запускаются существующие скрипты деплоя или тестов
    - echo "Запуск существующих сценариев..."
    - ./your_deploy_script.sh

    # 4. ЗАВЕРШЕНИЕ: сообщить Baserow "работа готова"
    - |
      curl -X PATCH \
        -H "Authorization: Token ${BASEROW_TOKEN}" \
        -H "Content-Type: application/json" \
        -d '{"Status": "Done", "Deploy Link": "'"$CI_PIPELINE_URL"'"}' \
        "https://api.baserow.io/api/database/rows/table/[YOUR_TABLE_ID]/${ROW_ID}/?user_field_names=true"
```

Проверить актуальную структуру JSON, которую отправляет Baserow, можно во вкладке «Last Trigger» настроенного вебхука.

**Как устроена логика:** `$TRIGGER_PAYLOAD` - переменная, в которую GitLab сохраняет данные строки, переданные Baserow при вызове; `jq` извлекает из неё `id` строки, инициировавшей событие. `curl -X PATCH` - универсальный способ обновить строку в [REST API Baserow](/docs/baserow/webhook-api/database-api/): захваченный `ROW_ID` гарантирует, что обновляется именно та запись, которая запросила сборку.

## Шаг 3. Настройка Baserow

Когда GitLab готов слушать, остаётся настроить Baserow на отправку запроса.

1. **Создайте Trigger Token в GitLab:** откройте **Settings → CI/CD → Pipeline triggers**, добавьте триггер (например, «Baserow») и скопируйте сгенерированный webhook URL (вида `https://gitlab.com/api/...token=TOKEN`).
2. **Создайте вебхук в Baserow:** откройте нужную таблицу, выберите **Webhooks** в меню таблицы, вставьте URL из GitLab в поле **URL**, укажите метод **POST** и выберите событие-триггер (например, «Row Created» или «Row Updated»).

Подробнее о механике самих вебхуков - в статье [«Вебхуки в Baserow»](/docs/baserow/webhook-api/webhooks/).

## Универсальность подхода

Схема работает независимо от конкретных названий столбцов - достаточно сопоставить поля в команде `curl` с реальными названиями столбцов таблицы.

| Сценарий | Триггер в Baserow | Действие в GitLab |
|---|---|---|
| Управление релизами | Создана строка в таблице «Releases» | Запуск `deploy_prod.sh` и обновление статуса Baserow на «Live» |
| Формирование отчёта | Статус изменён на «Generate Report» | Скрипт на Python собирает PDF и возвращает ссылку в Baserow |
| Выдача доступов сотруднику | Добавлена строка «New Employee» | Скрипт создаёт учётные записи и вставляет временный пароль обратно в Baserow |

## Обработка ошибок

Добавьте `after_script` в job GitLab - он выполняется даже при падении основного скрипта и позволяет отправить в Baserow статус `{"Status": "Failed"}`, чтобы команда сразу видела проблему:

```yaml
after_script:
    - |
      if [ "$CI_JOB_STATUS" != "success" ]; then
        curl -X PATCH -H "Authorization: Token ${BASEROW_TOKEN}" \
        -H "Content-Type: application/json" \
        -d '{"Status": "Failed"}' \
        "https://api.baserow.io/api/database/rows/table/[YOUR_TABLE_ID]/${ROW_ID}/?user_field_names=true"
      fi
```

## Часто задаваемые вопросы

**Можно ли обновить несколько столбцов за один вызов?** Да - в теле запроса `curl -d` можно перечислить сколько угодно пар поле-значение, например `{"Status": "Done", "deployed_at": "2024-01-01"}`.

**Как узнать, что запрос от Baserow вообще дошёл до GitLab?** Проверьте вкладку «Last Trigger» вебхука в Baserow - там показан код ответа и тело запроса, который был отправлен в GitLab.

**Обязательно ли использовать именно такие названия статусов?** Нет, названия статусов, полей и переменных в примерах условны - используйте те названия столбцов, которые уже приняты в вашей таблице, и просто подставьте их в JSON-тело запроса `curl`.

Смежные темы - [database-токены Baserow](/docs/baserow/webhook-api/personal-api-tokens/) для выпуска ключей с нужным набором прав и [обзор REST API Baserow](/docs/baserow/webhook-api/database-api/) для прямых вызовов без вебхуков.