Integrating CodeScene with GitLab Merge Requests

You can set up CodeScene to run delta analyses on your GitLab Merge Requests (MRs) and provide automated feedback via quality gates. This ensures that code health and quality standards are enforced early in the development process.

1. Prerequisites

  • Configure the CodeScene host URL under:
    Global Configuration → System → Host/Network Settings.

  • Ensure that your CodeScene instance is accessible from GitLab.

  • If you are running CodeScene locally (trial setup), see the Important Note at the end of this article.

2. Enable Merge Request Integration

  1. On the Projects page in CodeScene, locate your project.

  2. Navigate to:
    Project Configuration → PR Integration.

  3. Enable PR integration and select GitLab as the integration type.

3. Steps to Create a GitLab API Token

CodeScene requires a GitLab API token to access merge request data. You can use either a Personal Access Token or a Project Access Token:

1. Project Access Tokens

Project access tokens are scoped to a single project. They’re ideal when you want to limit access only to the repository CodeScene analyzes.

Steps to create a Project Access Token:

  1. Open your project in GitLab.

  2. Navigate to Settings → Access Tokens → Project Access Tokens.

  3. Click Add new token and fill in:

    • Token name: CodeScene Integration

    • Token description: Optional

    • Expiration date: Optional (recommended)

    • Role: e.g., Maintainer

    • Select scopes: api (required for CodeScene)

  4. Click Create token.

  5. Copy the generated token (shown only once).

2. Personal Access Tokens

Personal access tokens are tied to your user account and can access all projects your user has permission for.

Steps to create a Personal Access Token:

  1. Click your profile avatar → Edit profile → Access Tokens in GitLab.

  2. Click Add new token and fill in:

    • Token name: CodeScene Integration

    • Token description: Optional

    • Expiration date: Optional (recommended)

    • Role: e.g., Maintainer

    • Select scopes: api (required for CodeScene)

  3. Click Create token.

  4. Copy the generated token (shown only once).

4. Configure GitLab Credentials in CodeScene

  1. In CodeScene’s Pull Request Integration tab, choose one of the following:

    • Connection Settings Preset (created GitLab Presets (recommended))
      More information about presets can be found here.

    • Click Save Configuration.

    or

    • Paste the token created above in CodeScene under the GitLab Credentials field.

    • Click on toggle advanced settings and ensure that the GitLab API URL and CodeScene Host URL are correct.

      • GitLab API URL. If left blank, a default API URL is constructed from the repository paths.

      • CodeScene Host URL. The external webhooks will call CodeScene using this Host URL. If left blank, the global Host URL is used.

    • Click Save Configuration.

  2. Different configuration options are also available:

    • Post a Merge Request comment indicating when the MR check is pending
      When enabled, CodeScene will post a comment when it receives a webhook.

    • Add discussions to specific file locations
      Instead of posting one comment, CodeScene can add discussions to specific lines of files where code degradations or improvements occurred.

    • Don't resolve the discussion for high-risk Merge Requests
      When enabled, changes that are high-risk will have unresolved discussion threads, even if there are no degradations.

5. Customize MR Feedback

Automated Code Health Review & Code Quality Profile

  • Select a code quality profile that fits your project. We recommend starting with the Bare Minimum profile.

  • Can also be configured via: (Project) Configuration → Delta Analysis.

  • Learn more about quality profiles here.

6. Test the Configuration

  1. Create a Merge Request in GitLab.

  2. Verify that CodeScene posts its review and quality gates in the MR discussion thread.

Important Note for On-Premises Trials

When running CodeScene locally:

  • GitLab webhooks require inbound communication from GitLab’s servers to your CodeScene instance for webhook delivery.

  • If your instance is not publicly accessible, GitLab cannot deliver events.

Workaround:

  • Use a tunneling service such as ngrok to expose your local or private CodeScene server to the internet.

  • ngrok creates a temporary, secure bridge between GitLab and CodeScene, avoiding changes to your firewall or public IP configuration.