Interacting with BeeCR in GitLab

⚠️ Note: This documentation section assumes that you (or your project maintainer or DevOps) have already integrated BeeCR into your GitLab project. If not, do it using one of the following approaches:

• Via Webhook
• Via CI/CD job component (for GitLab 17+):
  • Component overview
  • Tutorial: Setup project via component
• Via CI/CD job template (for legacy GitLab):
  • Template overview
  • Tutorial: Setup project via template

🚀 Getting started

BeeCR reviews code patches in Merge Requests and adds review notes as comments to the files. Once a new Merge Request is created or code in the existing Merge Request has been updated, GitLab triggers BeeCR to review the code patch in the Merge Request.

To see BeeCR in action, follow this simple steps:

1. Let's assume that you already have a git branch named main and it contains some source code files. If not, just commit your code into the GitLab project's repository.
2. Create a new branch, for example, develop.
3. Under the develop branch, modify some source code files (or add new files) and push it to the repository.
4. Open a new Merge Request with the develop branch as the source and main as the target.
5. Navigate to the "Changes" tab and scroll to the file of your interest.

📄 Conventions

• BeeCR reviews code patches in Merge Requests only.
• BeeCR adds review notes as comments to the files.
• If the file already contains comments from BeeCR and has not been changed since the last review, BeeCR does not review the code patch for such file again.
• If the file has been changed since the last review, BeeCR will delete or hide its outdated comment:
  • The outdated comment will be simply removed if there are no replies to BeeCR's comments.
  • The outdated comment will be folded if there are replies to BeeCR's comments.

⚙️ Configuration via repository configuration file

BeeCR has a flexible settings system that can be managed in various ways. One of the most convenient ways is through the .beecr.yml configuration file in the repository root.

Using the .beecr.yml configuration file in the repository, you can configure the following project-specific parameters:

• model — AI model. Default value: gpt-4o (when using BeeCR SaaS cloud version) or ollama/codestral:22b (when using BeeCR on-premises installed on your server).
• ollama-host — Ollama server address.
• openai-host — OpenAI server address. Default value: https://api.openai.com.
• openai-api-key — Key for accessing OpenAI API. Default value: empty string.
• target — Regular expression for determining files to be checked. Default value: \.(py|c|h|cpp|hpp|cs|java|kt|swift|php|go|sh|(j|t)sx?)$.
• target-extra — Additional regular expression for determining files to be checked (useful when you don't want to completely override target, but only extend it). Default value: empty string.
• target-exclude — Regular expression for excluding files from checking (useful when you don't want to completely override target or target-extra). Default value: empty string.
• language — Language in which BeeCR will write comments. Default value: English.
• instructions — Additional instructions for passing additional context to the AI model or adjusting the code review process. Default value: empty string.
• note-trigger — Trigger expression monitored in user comments. Default value: /beecr.

Example configuration file:

.beecr.yml

model: 'gpt-4o'
ollama-host: 'http://my-ai-server:11434'
openai-host: 'https://api.openai.com'
openai-api-key: 'sk-my-openai-api-key'
target: '\.(py|c|h|cpp|hpp|cs|java|kt|swift|php|go|sh|(j|t)sx?)$'
target-extra: '\.hs$'
target-exclude: '\.sh$'
language: 'English'
instructions: 'Do not focus on code style, highlight bugs only.'
note-trigger: '/ai'

For more detailed information about all parameters and configuration methods, you can refer to the documentation sections BeeCR GitLab webhook: Configuration and BeeCR API server settings.

🪝 Features of integration BeeCR via webhooks

⚠️ Note: The information in this section is relevant only if you integrated BeeCR via webhooks. Skip reading this section if BeeCR has been integrated via CI/CD job component or template.

▶️ Manual review initiation

You can initiate the review process manually by leaving comments on your Merge Request if "Comments" events has been enabled for the webhook. Comments that trigger the review must contain the special keyword /beecr (configurable).

Pass extra instructions via comments

Along with the keyword, you can provide additional information to give the AI model more context or to adjust the review process. For example:

• /beecr Do not focus on code style; highlight bugs only.
• /beecr Review for security issues only.
• /beecr Provide short comments, pointing out a maximum of 5 issues.

Review single file

Leave a comment on a specific file in your Merge Request to initiate the review of that file. In this case, any settings that define the target set of files will be ignored.

Review all target files

Leave a comment on the entire Merge Request to review all files targeted by the "target" parameters set.

⚠️ Note: By default, the review is enabled 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

However, you can configure it the way you wish to support more languages or vice versa, to suppress some of the defaults.

🔄 Features of integration BeeCR via CI/CD

⚠️ Note: The information in this section is relevant only if you integrated BeeCR via CI/CD job component or template. Skip reading this section if BeeCR has been integrated via the webhook.

🔕 Skip the beecr CI/CD job

The beecr job is not triggered if the commit message contains any of the following messages:

• :mute:, [mute]
• :no-review:, :no_review:, :no review:, [no review], [no-review], [no_review]
• :skip-review:, :skip_review:, :skip review:, [skip-review], [skip_review], [skip review]

📃 The beecr CI/CD job logs

For some reasons, you may want to see the logs of the BeeCR job.

1. Navigate to the list of CI/CD pipelines in your project (unfold the "Build" menu in the sidebar and press "Pipelines").
2. Select the pipeline relevant to your Merge Request.
3. Navigate to the BeeCR job in your pipeline's details.

In the example above, the BeeCR job produced a report with the following response:

{
  "code": 200,
  "message": "Review finished successfully.",
  "success": true,
  "total_changes_count": 1,
  "total_discussions_count": 1,
  "reviews": [
    {
      "success": true,
      "reviewed": true,
      "message": "Reviewed because the file has never been reviewed before.",
      "type": "file",
      "old_path": "examples/service.h",
      "new_path": "examples/service.h"
    }
  ]
}

Some information we could obtain from this example report: * The review procedure finished successfully. * One file in the Merge Request has been reviewed: examples/service.h * BeeCR left comments on the examples/service.h file because the file has never been reviewed before.

▶️ Manual beecr CI/CD job execution

By default, the beecr CI/CD job executes automatically. However, it is possible to set up the job to execute manually. If you (or your project maintainer or DevOps) set up the manual execution of the beecr job, you need to execute it explicitly to perform the review process:

1. Go to the pipeline with the beecr job.
2. Next to the manual job, click on the run button ▶.

Refer to this GitLab documentation section to learn more about manual job execution.

To learn how to set up manual job execution, navigate to the relevant section in the documentation about integrating BeeCR via CI/CD:

• Component overview (for GitLab 17+)
• Template overview (for legacy GitLab)