Skip to content

Tutorial: Setup modern GitLab 17+ project

Welcome to the "Setup modern GitLab 17+ project" tutorial. This guide will walk you through the process of setting up a modern 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 modern GitLab 17+ project for BeeCR. If you are looking for documentation on the CI/CD component (the modern approach generally available in GitLab 17+), please refer to this document. 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.

📄 Prerequirements

  1. You have an access to BeeCR SaaS or deployed an on-premises server.
  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 convinient if you are going to use BeeCR accross 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. Give it 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 component

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 component using the include keyword.

stages:
  - review

include:
  - component: gitlab.com/cvisionlab/beecr/beecr@main

💡 Tip: If you are using a self-hosted GitLab and remote CI/CD component inclusion is not permitted by your organization's policy, you may mirror our repo or simply copy and paste the content of the component.

5️⃣ Perform additional configuration

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

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

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 url option with the BeeCR service URL (e.g. http://SERVER:8000).

Example of configuration:

stages:
  - review

include:
  - component: gitlab.com/cvisionlab/beecr/beecr@main
    inputs:
      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 define the target option 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 target-extra option as \.md$.
  • If you are partially satisfied with the default but want to exclude some extensions (e.g., .sh), then we recommend defining the target-exclude option as \.sh$

Example:

stages:
  - review

include:
  - component: gitlab.com/cvisionlab/beecr/beecr@main
    inputs:
      target-exclude: '\.sh$'

👍 Conclusion

In conclusion, you have learned how to set up a modern GitLab 17+ project for BeeCR by creating access tokens, enabling CI/CD, configuring essential parameters, and including the CI/CD component. 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.