Skip to content

BeeCR GitLab webhook

⚠️ Note: This section describes how to set up code review as a GitLab Webhook. If you prefer to use CI/CD, please refer to the alternative integration methods:

🚀 Quick start

  1. Create a new GitLab webhook at your project.
  2. Set the webhook URL to: 
    https://beecr.io/api/v1/gitlab-review?asynchronous=True
  3. Define the following headers:
    • BEECR-API-KEY with your API key provided to you by the BeeCR team
      (required only if you are using BeeCR SaaS).
    • BEECR-GITLAB-TOKEN with your GitLab access token (project or group). The token must have at least developer-level permissions with the "api" scope.

      💡 Tip: We recommend you to create project or group token giving it a nice name, such as BeeCR Code Reviewer, because code review comments will be authored by GitLab Bot under this name.

  4. Set trigger to Comments events.

Webhook main configuration

That's it. Now you are able to trigger the review of a certain file in your opened Merge Request by leaving a comment with the /beecr keyword on the file's diff.

🪝 Webhook URL

For the SaaS version, use the following URL: https://beecr.io/api/v1/gitlab-review?asynchronous=True

For the on-premises version, replace https://beecr.io in the SaaS URL with your server's address and port, for example: http://192.168.128.77:8000.

⚠️ Note: Passing asynchronous=True tells the server to perform the request in an asynchronous manner. This means that it will respond quickly and schedule the actual review in the internal processing queue. This is essential when using this endpoint as a GitLab webhook because GitLab requires webhooks to respond in about 10 seconds or less.

🔌 Events

GitLab allows you to enable triggering a webhook via various types of events. BeeCR webhook support the following two types:

Comments events

When the Comments event is enabled, BeeCR will review changes in Merge Requests if someone leaves a comment containing /beecr (the trigger word is configurable if necessary).

Webhook Comments events configuration

Depending on where the comment is left, BeeCR will review changes in a single specific file or changes in all target files:

  • If the comment is made anywhere in the thread related to changes in a specific file, only that file will be reviewed.
  • If the comment is made in the Merge Request outside of the specific file thread, then all "target" files will be reviewed.

Merge Request events

When the Merge Request event is enabled, BeeCR will automatically review changes in "target" files each time a Merge request is created or the code in the Merge Request is updated.

Webhook Merge Request events configuration

🛠 Configuration

Most of the parameters can be configured in four ways:

  1. Via HTTP headers.
  2. Via query parameters (part of the URL).

    ⚠️ Note: HTTP URLs require URL encoding procedures for the query parameters. When passing options via query parameters, ensure that you apply URL encoding using any method that works for you (e.g., via https://urlencoder.org).

  3. Via the configuration file .beecr.yml in the root of your repository. Example:
    .beecr.yml
    target: '\.(py|c|h|cpp|hpp|cs|sh|(j|t)sx?|md|tf|vue)$'
language: English
instructions: Do not focus on code style, highlight bugs only.
  4. Via the API server's settings (if you are using BeeCR on-premises).

We recommend:

  • In general:
    • set all secrets (API keys and tokens) via headers
    • all other parameters via the configuration file .beecr.yml
  • For on-premises clients:

⚠️ Note: Below you can find the description of the supported options and ways to define them. Please pay special attention to options marked with ⭐.

API key (SaaS) ⭐

The API key is only required if you are using BeeCR SaaS.

Ways to define the API key:

  • Header BEECR-API-KEY in webhook settings (⭐ recommended).
  • Query parameter api-key in webhook URL.

GitLab token ⭐

BeeCR needs the GitLab access token (for project or group). The token must have at least developer-level permissions with the "api" scope.

💡 Tip: We recommend you to create project or group token giving it a nice name, such as BeeCR Code Reviewer, because code review comments will be authored by GitLab Bot under this name.

Ways to define the GitLab host:

  • Header BEECR-GITLAB-TOKEN in webhook settings (⭐ recommended).
  • Query parameter gitlab-token in webhook URL.
  • Via the GITLAB_TOKEN API server's parameter (applicable only if you are using BeeCR on-premises).

GitLab host

Normally, you don't need to set the GitLab host since it can be obtained from the payload that GitLab posts automatically. However, in some cases (e.g., sophisticated network setup), you may wish to set it explicitly.

Ways to define the GitLab host:

  • Header BEECR-GITLAB-HOST in webhook settings.
  • Query parameter gitlab-host in webhook URL.
  • Via the GITLAB_HOST API server's parameter (applicable only if you are using BeeCR on-premises).

By default the GitLab host is set to https://gitlab.com.

AI model name (on-premises)

On the backend, BeeCR on-premises can use AI models via two different APIs: OpenAI and Ollama. Clients may choose which API to use:

  • For OpenAI-compatible APIs use model names as they are.
    Example: gpt-4o.
  • For Ollama-compatible APIs use model names with the prefix ollama/.
    Example: ollama/codestral:22b.

By default, the model is set to ollama/codestral:22b.

Ways to redefine the AI model:

  • Header BEECR-MODEL in webhook settings.
  • Query parameter model in webhook URL.
  • Property model in the YAML configuration file .beecr.yml in the root of your repository.
  • Via the MODEL API server's parameter.

Ollama (on-premises) ⭐

To use models served by AI server with Ollama API you may need to define the Ollama host.

Ways to define the Ollama host:

  • Header BEECR-OLLAMA-HOST in webhook settings.
  • Query parameter ollama-host in webhook URL.
  • Property ollama-host in the YAML configuration file .beecr.yml in the root of your repository.
  • Via the OLLAMA_HOST API server's parameter (⭐ recommended and applicable only for BeeCR on-premises clients).

OpenAI (on-premises) ⭐

To use models via OpenAI API you may need to define the OpenAI host and OpenAI API key. By default, the OpenAI host is set to https://api.openai.com, which suits the needs of most clients.

Ways to redefine the OpenAI host:

  • Header BEECR-OPENAI-HOST in webhook settings.
  • Query parameter openai-host in webhook URL.
  • Property openai-host in the YAML configuration file .beecr.yml in the root of your repository.
  • Via the OPENAI_HOST API server's parameter (applicable only for BeeCR on-premises clients).

Ways to define the OpenAI API key:

  • Header BEECR-OPENAI-API-KEY in webhook settings (⭐ recommended).
  • Query parameter openai-api-key in webhook URL.
  • Property openai-api-key in the YAML configuration file .beecr.yml in the root of your repository.
  • Via the OPENAI_API_KEY API server's parameter (applicable only for BeeCR on-premises clients).

Review target settings

Target ⭐

The "target" defines a regex pattern for matching files.

By default, the target regex is \.(py|c|h|cpp|hpp|cs|java|kt|swift|php|go|sh|(j|t)sx?)$ which enables the review for files with the following languages:

  • 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

Ways to redefine the the "target":

  • Header BEECR-TARGET in webhook settings.
  • Query parameter target in webhook URL.
  • Property target in the YAML configuration file .beecr.yml in the root of your repository (⭐ recommended).
  • Via the TARGET API server's parameter (applicable only for BeeCR on-premises clients).

Extra target

The "extra target" defines an additional regex pattern for matching files. Useful if you don't want to redefine the "target" completely.

By default, the "extra target" regex is empty.

Ways to define the the "extra target":

  • Header BEECR-TARGET-EXTRA in webhook settings.
  • Query parameter target-extra in webhook URL.
  • Property target-extra in the YAML configuration file .beecr.yml in the root of your repository.
  • Via the TARGET_EXTRA API server's parameter (applicable only for BeeCR on-premises clients).

Exclude from target

The "exclude from target" defines a regex pattern to exclude files from review (even if they are matched by the "target" or "extra target"). Useful if you don't want to redefine the "target" or "extra target".

By default, the "exclude from target" regex is empty.

Ways to define the the "extra target":

  • Header BEECR-TARGET-EXCLUDE in webhook settings.
  • Query parameter target-exclude in webhook URL.
  • Property target-exclude in the YAML configuration file .beecr.yml in the root of your repository.
  • Via the TARGET_EXCLUDE API server's parameter (applicable only for BeeCR on-premises clients).

Review language

By default, review comments will be produced in English (recommended for best quality).

Ways to redefine the the "language":

  • Header BEECR-LANGUAGE in webhook settings.
  • Query parameter language in webhook URL.
  • Property language in the YAML configuration file .beecr.yml in the root of your repository.
  • Via the LANGUAGE API server's parameter (applicable only for BeeCR on-premises clients).

Additional instructions

You can provide additional instructions as text to give the AI model more context or adjust the code review process.

Ways to provide additional instructions:

  • Key instructions in the .beecr.yml configuration file in your repository root. Example:
    .beecr.yml
    instructions: "Do not focus on code style, highlight only errors."
  • In file or MR comments along with the /beecr keyword (only works when integrated via webhook with "Comments" events enabled). Example: 
    /beecr Check only security issues.

Repository configuration path

By default, the API server will try to get settings from the .beecr.yml file in project's repository root, which suits the needs of most clients.

Ways to redefine the the path to the configuration file in repository:

  • Header BEECR-REPO-CONFIG-PATH in webhook settings.
  • Query parameter repo-config-path in webhook URL.
  • Property repo-config-path in the YAML configuration file .beecr.yml in the root of your repository.
  • Via the REPO_CONFIG_PATH API server's parameter (applicable only for BeeCR on-premises clients).

Trigger in notes

If BeeCR integrated via webhooks for "Comments" events then it will review the changes in MR if the special trigger-word has been mentioned in the note.

By default, the review process will trigger by /beecr, which suits the needs of most clients.

Ways to redefine the trigger-word:

  • Header BEECR-NOTE-TRIGGER in webhook settings.
  • Query parameter note-trigger in webhook URL.
  • Property note-trigger in the YAML configuration file .beecr.yml in the root of your repository.
  • Via the NOTE_TRIGGER API server's parameter (applicable only for BeeCR on-premises clients).