Skip to content

Tutorial: Setup legacy GitLab project

Welcome to the "Setup legacy GitLab project" tutorial. This guide will walk you through the process of setting up a legacy GitLab project for BeeCR. This tutorial covers the prerequisites and essential steps required to configure your GitLab project effectively.

⚠️ Note: This tutorial describes how to set up a legacy GitLab project for BeeCR. If you are looking for documentation on the CI/CD job template (which works in both modern GitLab 17+ and older GitLab versions), please refer to this document. If you are looking for documentation on the CI/CD component (the modern approach generally available in GitLab 17+), please refer to this document.

📄 Prerequirements

  1. You have access to BeeCR SaaS (via API key) or have deployed an BeeCR on-premises.
  2. You have permission to set up GitLab project's settings and create access tokens.

1️⃣ Create an access token

BeeCR needs access to your repository to review code. Therefore, you need to create an access token first. GitLab provides several types of tokens:

We recommend you to create project or group token. Group token is more convenient if you are going to use BeeCR across multiple projects in the same group.

Here are guide:

  1. To create a token, navigate to project's or group's "Settings", then "Access Tokens" and create Add new token.
  2. The token must have at least developer-level permissions with the "api" scope.
  3. Givit it a nice name, such as BeeCR Code Reviewer, because code review comments will be authored by GitLab Bot under this name.

2️⃣ Ensure CI/CD is enabled

Skip this step if you are familiar with GitLab CI/CD and are confident that your project uses it. Otherwise, we recommend ensuring that CI/CD is enabled and that at least one GitLab runner is available in your project's settings:

  1. Navigate to the project's "Settings," then "General," and scroll to "Visibility, project features, permissions." The "CI/CD" option must be enabled.
  2. Navigate to the project's "Settings," then "CI/CD," and expand the "Runners" section. Ensure that at least one runner (project, instance, or group) is available.

If your project does not have CI/CD, please ask your GitLab maintainer, system administrator, or DevOps team.

3️⃣ Configure essential parameters

Define the following CI/CD variables in your project or group (or even the entire GitLab instance if you wish and have permission):

  • BEECR_API_KEY with an API key provided by the BeeCR team.
    This is required only if you are using BeeCR as a SaaS.
    Simply skip setting this variable if you plan to use the on-premises version.
  • BEECR_GITLAB_TOKEN with the GitLab access token you created in one of the previous steps.

Define the following CI/CD variable in your project or group (or even the entire GitLab instance if you wish and have permission):

  • BEECR_GITLAB_TOKEN with the GitLab access token you created in one of the previous steps.

4️⃣ Include the CI/CD job template

Create (or modify if it exists) a .gitlab-ci.yml file in the root of your repository by adding a review stage to the stages definition and including the beecr template using the include keyword.

stages:
  - review

include:
  - remote: 'https://gitlab.com/cvisionlab/beecr/-/raw/main/templates/beecr/template-always.yml'

💡 Tip: If you are using a self-hosted GitLab and remote job template inclusion is not permitted by your organization's policy, you may mirror our repo at https://gitlab.com/cvisionlab/beecr/ into your GitLab or simply copy and paste the content of the job template.

⚠️ Note: For some reasons, you may wish to control the code review job execution manually. For those purposes, simply include the template-manual.yml file instead of template-always.yml.

5️⃣ Perform additional configuration

The default options set in the provided CI/CD job template satisfy the needs of most users. However, you may wish to adjust some settings.

The job can be configured via environment variables in two alternative ways:

Here are a couple of examples below. For more information on available options, please refer to the relevant documentation for CI/CD job templates.

API URL

If you are going to use BeeCR on-premises, you need to specify the URL of the service where you deployed it. Otherwise, simply skip setting this variable if you plan to use the SaaS version.

To do that just set BEECR_URL variable with the BeeCR service URL (e.g. http://SERVER:8000).

Example (deep merging):

stages:
  - review

include:
  - remote: 'https://gitlab.com/cvisionlab/beecr/-/raw/main/templates/beecr/template-always.yml'

beecr:
  variables:
    BEECR_URL: 'http://SERVER:8000'

Replace SERVER:8000 in the example above with the address of your target server and port.

Files to review

Another example is configuring the list of target extensions to review. By default, the review is enabled for files with the following extensions:

  • 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

You have multiple options to modify this list. Here are some scenarios and proposed methods:

  • If you wish to significantly reduce this list of supported extensions (e.g., keep .java only), then redefine the BEECR_TARGET variable as \.java$.
  • If you are satisfied with the default list but want to add more (e.g., .md), then the most convenient way would be to define the BEECR_TARGET_EXTRA variable as \.md$.
  • If you are partially satisfied with the default but want to exclude some extensions (e.g., .sh), then we recommend defining the BEECR_TARGET_EXCLUDE variable as \.sh$

Example (deep merging):

stages:
  - review

include:
  - remote: 'https://gitlab.com/cvisionlab/beecr/-/raw/main/templates/beecr/template-always.yml'

beecr:
  variables:
    BEECR_TARGET_EXCLUDE: '\.sh$'

👍 Conclusion

In conclusion, you have learned how to set up a legacy GitLab project for BeeCR by creating access tokens, enabling CI/CD, configuring essential parameters, and including the CI/CD job template. By following these steps, you have ensured that your GitLab project is ready for code review processes. If you need further assistance or additional information, feel free to refer back to this tutorial or reach out to BeeCR support.