Перейти к содержанию

Вебхук BeeCR для GitLab

⚠️ Примечание: Этот раздел описывает настройку проверки кода в GitLab через Вебхук. Если вы предпочитаете использовать CI/CD, обратитесь к альтернативным методам интеграции:

🚀 Краткая инструкция

  1. Создайте новый вебхук в вашем проекте на GitLab.
  2. Установите полный URL вебхука, ссылающийся на конечную точку /gitlab-review?asynchronous=True.
    Например, для версии SaaS полный URL выглядит следующим образом: 
    https://beecr.io/api/v1/gitlab-review?asynchronous=True
  3. Определите следующие HTTP-заголовки:
    • BEECR-API-KEY – ваш API-ключ, предоставленный вам командой BeeCR
      (необходим только при использовании BeeCR SaaS).
    • BEECR-GITLAB-TOKEN – токен доступа к GitLab, который вы должны выпустить для проекта или группы проектов). Токен должен иметь права как минимум уровня "Developer" и предоставлять доступ к "api".

      💡 Совет: Мы рекомендуем присвоить токену осмысленное имя, например, BeeCR Code Reviewer, поскольку комментарии к коду будут написаны ботом, представляющимся этим именем.

    • BEECR-OPENAI-API-KEY – ваш API-ключ доступа к OpenAI
      (необходим только при использовании моделей от OpenAI).
  4. Установите триггер на события Comments.

Webhook main configuration

Теперь вы можете запустить проверку изменений в файле в вашем открытом запросе на слияние (Merge Request), оставив комментарий с со специальным выражением /beecr к конкретному файлу.

🪝 URL

Полный URL вебхука, ссылающийся на конечную точку /gitlab-review?asynchronous=True.

Полный URL должен содержать адрес API-сервера BeeCR. Конкретное значение зависит от того, где размещен сервер API:

  • Для версии SaaS используйте следующий URL:
    https://beecr.io/api/v1/gitlab-review?asynchronous=True
  • Если сервер API BeeCR размещен локально, вам нужно самостоятельно определить адрес. Например:
    http://192.168.128.77:8000/gitlab-review?asynchronous=True

Параметр asynchronous=True даёт указание API-серверу BeeCR выполнять запрос в асинхронном режиме. Это означает, что сервер ответит быстро, но запланирует фактическую проверку во внутренней очереди обработки. Это является важным аспектом, так как GitLab требует, чтобы вебхуки отвечали примерно за 10 секунд или быстрее.

🔌 Выбор событий для реакции

GitLab позволяет вам активировать срабатывание вебхука через различные типы событий. Вебхук BeeCR поддерживает следующие два типа:

События "Comments"

В случае выбора событий типа Comments, BeeCR будет проверять изменения в запросах на слияние если кто-то оставляет комментарий, содержащий специальное выражение /beecr (можно изменить при необходимости).

События Comments

В зависимости от того, где именно оставлен комментарий, BeeCR будет проверять изменения в одном конкретном файле или изменения во всех целевых файлах:

  • Если комментарий оставлен где-либо в обсуждении, связанном с изменениями в определенном файле, то будет проверен только этот файл. В этом случае любые настройки, определяющие набор целевых файлов, будут проигнорированы.
  • Если же комментарий оставлен ко всему запросу на слияние, а не к конкретному файлу в рамках запроса, то будут проверены изменения во всех "целевых" файлах.

    ⚠️ Примечание: Список "целевых" файлов для проверки по умолчанию пуст. Убедитесь, что вы настроили цели либо в параметрах вебхука, либо в настройках API-сервера (если вы используете BeeCR, развернутый на вашем сервере).

События "Merge Request"

В случае выбора событий типа Merge Request, BeeCR автоматически будет проверять изменения в "целевых" файлах каждый раз, когда создается запрос на слияние или код в запросе на слияние обновляется.

Собоытия Merge Request

⚠️ Примечание: Список "целевых" файлов для проверки по умолчанию пуст. Убедитесь, что вы настроили цели либо в параметрах вебхука, либо в настройках API-сервера (если вы используете BeeCR, развернутый на вашем сервере).

🛠 Конфигурирование

Большинство параметров BeeCR можно настроить четырьмя способами:

  1. Через HTTP-заголовки.
  2. Через параметры запроса (т.е. как часть URL).

    ⚠️ Примечание: Согласно техническим стандартам web при передачи параметров в URL требуется проведение процедуры кодирования (т.н. URL encoding).
    При передаче параметров через URL убедитесь, что вы применили URL encoding, используя любой удобный для вас инструмент (например, через online ресурс https://urlencoder.org).

  3. Через файл конфигурации .beecr.yml в корне вашего репозитория. Пример: 
    target: '\.(py|c|h|cpp|hpp|cs|sh|(j|t)sx?|md|tf|vue)$'
language: English
  4. В настройках API-сервера (если вы используете BeeCR, развернутый на вашем сервере).

Мы рекомендуем:

  • В общем случае:
    • устанавливайте все секреты (API-ключи и токены) через HTTP-заголовки, т.к. это наиболее безопасно;
    • устанавливайте все остальные параметры через конфигурационный файл .beecr.yml (например, "целевые" файлы для проверки, модель, язык и т.д.), т.к. это наиболее удобно.
  • Для пользователей, устанавливающих API-сервер локально:
    • рассмотрите возможность задания некоторых параметров через настройки API-сервера, если посчитаете это более удобным.

⚠️ Примечание: Ниже вы найдете описание поддерживаемых параметров и способы их определения. Пожалуйста, уделите особое внимание параметрам, отмеченным ⭐.

API-ключ (SaaS) ⭐

API-ключ требуется только при использовании облачной версии BeeCR SaaS.

Способы задания ключа API:

  • HTTP-заголовок BEECR-API-KEY в настройках вебхука (⭐ рекомендованный способ).
  • Параметр запроса api-key в URL вебхука.

Токен доступа к GitLab ⭐

Для корректной работы BeeCR требуется выпустить токен доступа к GitLab (проектный или групповой). Токен должен иметь права как минимум уровня "Developer" и предоставлять доступ к "api".

💡 Совет: Дайте токену осмысленное имя, например, "BeeCR Code Reviewer", поскольку комментарии к коду будут написаны ботом, представляющимся этим именем.

Способы задания токена доступа к GitLab:

  • HTTP-заголовок BEECR-GITLAB-TOKEN в настройках вебхука (⭐ рекомендованный способ).
  • Параметр запроса gitlab-token в URL вебхука.
  • Настройка API-сервера GITLAB_TOKEN (применимо только если вы используете BeeCR, развернутый на вашем сервере).

Адрес GitLab

В большинстве случаев при использовании интеграции BeeCR через вебхуки вам не нужно заботится о задании адреса GitLab, так как BeeCR получает адрес автоматически из данных, которые GitLab передаёт в теле HTTP-запроса. Однако в некоторых случаях (например, нетривиальная настройка вашей локальной сети) автоматическое определение адреса может не сработать и тогда вам потребуется задать адрес явно.

Способы задания адреса GitLab:

  • HTTP-заголовок BEECR-GITLAB-HOST в настройках вебхука.
  • Параметр запроса gitlab-host в URL вебхука.
  • Настройка API-сервера GITLAB_HOST (применимо только если вы используете BeeCR, развернутый на вашем сервере).

Значение адреса GitLab умолчанию: https://gitlab.com.

Модель ИИ

BeeCR может использовать различные модели искусственного интеллекта через два альтернативных API: OpenAI и Ollama. При желании пользователи могут сами выбрать, какую модель через какое API использовать:

  • В случае использование OpenAI API, используйте оригинальные названия моделей (т.е. "как есть"). Пример: gpt-4o.
  • В случае использование Ollama API, используйте названия моделей с префиксом ollama/. Пример: ollama/codestral:22b.

Значение по умолчанию:

  • gpt-4o в BeeCR SaaS (облачная версия).
  • ollama/codestral:22b в BeeCR on-premises (версия для установки на вашем сервере).

Способы задания модели:

  • HTTP-заголовок BEECR-MODEL в настройках webhook.
  • Параметр запроса model в URL webhook.
  • Ключ model в конфигурационном файле .beecr.yml в корне вашего репозитория.
  • Настройка API-сервера MODEL (применимо только если вы используете BeeCR, развернутый на вашем сервере).

Ollama ⭐

⚠️ Примечание: Информация в этом разделе актуальна только в том случае, если вы собираетесь использовать модели через Ollama API.

Для использования моделей через Ollama, вам может потребоваться определить адрес сервера Ollama.

Способы определения адреса сервера Ollama:

  • HTTP-заголовок BEECR-OLLAMA-HOST в настройках webhook.
  • Параметр запроса ollama-host в URL webhook.
  • Ключ ollama-host в конфигурационном файле .beecr.yml в корне вашего репозитория.
  • Настройка API-сервера OLLAMA_HOST (⭐ рекомендованный способ; применимо только если вы используете BeeCR, развернутый на вашем сервере).

OpenAI ⭐

⚠️ Примечание: Информация в этом разделе актуальна только в том случае, если вы собираетесь использовать модели через OpenAI API.

Для использования моделей через OpenAI API, вам может потребоваться определить адрес сервера OpenAI и API-ключ. По умолчанию адрес OpenAI установлен как https://api.openai.com, что подходит большинству пользователей.

Способы задания адреса OpenAI:

  • HTTP-заголовок BEECR-OPENAI-HOST в настройках вебхука.
  • Параметр запроса openai-host в URL вебхука.
  • Ключ openai-host в конфигурационном файле .beecr.yml в корне вашего репозитория.
  • Настройка API-сервера OPENAI_HOST (⭐ рекомендованный способ; применимо только если вы используете BeeCR, развернутый на вашем сервере).

Способы задания API-ключа:

  • HTTP-заголовок BEECR-OPENAI-API-KEY в настройках вебхука (⭐ рекомендованный способ).
  • Параметр запроса openai-api-key в URL вебхука.
  • Ключ openai-api-key в конфигурационном файле .beecr.yml в корне вашего репозитория.
  • Настройка API-сервера OPENAI_API_KEY (применимо только если вы используете BeeCR, развернутый на вашем сервере).

Настройки цели для проверки

Основная настройка (target) ⭐

Параметр "target" позволяет задать регулярное выражение для определения файлов, подлежащих проверке.

Значение по умолчанию:

\.(py|c|h|cpp|hpp|cs|java|kt|swift|php|go|sh|(j|t)sx?)$

Использование данного регулярного выражения приведет к проверке файлов для следующих языков программирования:

  • Python: .py
  • C/C++: .h, .hpp, .c, .cpp
  • C#: .cs
  • Java: .java
  • Kotlin: .kr
  • Swift: .swift
  • PHP: .php
  • Go: .go
  • Bash/Shell: .sh
  • JavaScript/Typescript: .js, .jsx, .mjs, .mjsx, .ts, .tsx

Однако вы можете настроить ее так, как вам удобно, чтобы поддерживать больше языков или, наоборот, исключить некоторые из стандартных. Пример регулярного выражения:

\.(java|hs)$

Способы задания параметра "target":

  • HTTP-заголовок BEECR-TARGET в настройках вебхука.
  • Параметр запроса target в URL вебхука.
  • Ключ target в конфигурационном файле .beecr.yml в корне вашего репозитория (⭐ рекомендованный способ).
  • Настройка API-сервера BEECR_TARGET (применимо только если вы используете BeeCR, развернутый на вашем сервере).

Дополнительная настройка (target extra)

Параметр "target extra" аналогичен параметру "target". Он позволяет задать дополнительное регулярное выражение для определения файлов, подлежащих проверке. Наличие такой настройки полезно в тех случаях, когда вы не хотите полностью переопределять "target", а лишь немного расширить его.

По умолчанию, параметр "target extra" пуст.

Способы задания параметра "target extra":

  • HTTP-заголовок BEECR-TARGET-EXTRA в настройках вебхука.
  • Параметр запроса target-extra в URL вебхука.
  • Ключ target-extra в конфигурационном файле .beecr.yml в корне вашего репозитория.
  • Настройка API-сервера BEECR_TARGET_EXTRA (применимо только если вы используете BeeCR, развернутый на вашем сервере).

Настройка исключений (target exclude)

Параметр "target exclude" позволяет задать регулярное выражение для исключения файлов из проверки (даже если они подпадают под действие "target" или "target extra"). Наличие такой настройки полезно в тех случаях, когда вы не хотите полностью переопределять "target" или "target extra".

По умолчанию, параметр "target exclude" пуст.

Способы задания параметра "target exclude":

  • HTTP-заголовок BEECR-TARGET-EXCLUDE в настройках вебхука.
  • Параметр запроса target-exclude в URL вебхука.
  • Ключ target-exclude в конфигурационном файле .beecr.yml в корне вашего репозитория.
  • Настройка API-сервера BEECR_TARGET_EXCLUDE (применимо только если вы используете BeeCR, развернутый на вашем сервере).

Язык проверки

По умолчанию, комментарии к проверке будут создаваться на английском языке (English). Мы рекомендуем использовать английский язык, так как в этому случае комментарии от модели ИИ наиболее полные и качественные для всех протестированных моделей.

Способы задания "языка":

  • HTTP-заголовок BEECR-LANGUAGE в настройках вебхука.
  • Параметр запроса language в URL вебхука.
  • Ключ language в конфигурационном файле .beecr.yml в корне вашего репозитория.
  • Настройка API-сервера BEECR_LANGUAGE (применимо только если вы используете BeeCR, развернутый на вашем сервере).

Путь к конфигурационному файлу в репозитории

Как отмечалось ранее, по умолчанию API-сервер попытается получить настройки в т.ч. из файла .beecr.yml в корне репозитория проекта. Такой вариант подойдет большинству пользователей. Однако вы можете задать другой путь к файлу (относительно корня репозиторя) если пожелаете.

Способы задания пути к конфигурационному файлу в репозитории:

  • HTTP-заголовок BEECR-REPO-CONFIG-PATH в настройках вебхука.
  • Параметр запроса repo-config-path в URL вебхука.
  • Настройка API-сервера REPO_CONFIG_PATH (применимо только если вы используете BeeCR, развернутый на вашем сервере).

Специальное выражение-триггер для комментариев

В случае интеграции BeeCR через вебхуки для событий "Comments" проверка изменений в запросе на слияние будет выполнятся в том случае, если кто-то оставил комментарий в соответствующем запросе на слияние с упоминанием специального выражения /beecr:

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

Вы можете задать другое выражение-триггер вместо /beecr, если пожелаете. Способы задания выражения-триггера:

  • HTTP-заголовок BEECR-NOTE-TRIGGER в настройках вебхука.
  • Параметр запроса note-trigger в URL вебхука.
  • Ключ note-trigger в конфигурационном файле .beecr.yml в корне вашего репозитория.
  • Настройка API-сервера BEECR_NOTE_TRIGGER (применимо только если вы используете BeeCR, развернутый на вашем сервере).