Documentation

Doc index page

Analyze a Drupal module on GitLab

While SensioLabsInsight main expertise is on Symfony, SensioLabsInsight is also used by many Drupal modules developers to ensure high quality coding standards. SensioLabsInsight is indeed able to analyze Drupal modules and give you thorough details about potential improvements.

The aim of this document is to fully setup the SensioLabsInsight integration of a public or private Drupal module hosted on a GitLab instance (GitLab.com or a custom GitLab).

Note

This document considers that your GitLab repository is accessible by SensioLabsInsight. If it is not, referer to the corresponding section "Analyze projects not accessible by SensioLabsInsight".

SensioLabsInsight does not offer native support GitLab commit statuses. However, we will achieve in this document a similar result using the Insight SDK in your Continuous Integration platform (for instance GitLab CI).

Create the project

1 Before adding your project on SensioLabsInsight, you need to obtain the SSH key SensioLabsInsight will use to clone your repository and add it to GitLab so it will be authorized.

To do so, go on https://connect.sensiolabs.com/#!ssh and check the Manage your private SSH key section. If the section displays a key, copy its contents. Otherwise, click the Generate button to create your SSH key and copy its contents.

2 In GitLab, go into your Settings and in the SSH keys section. Paste the SSH key in the form and click on Add key.

3 In SensioLabsInsight, click on the Add project link located at the top of the right sidebar of your dashboard.

4 In the field Git Repository URL, paste the SSH Git repository URL of your GitLab project (it should look like this: git@gitlab.com:yourusername/yourproject.git).

Choose the Drupal module project type to enable the rules for Drupal modules.

Finally, click on the Analyze button and SensioLabsInsight will start the analysis immediately.

Configure your Continuous integration platform for commits and Merge Requests

Your project is now created. The next logical step is to configure it to be analyzed on each commit and Merge Request to ensure the code quality is not decreasing along the project lifetime.

Note

To integrate SensioLabsInsight into GitLab Merge Requests, you will need a Continuous Integration platform configured on repository. If you don't have one, you can use GitLab CI.

This section will use GitLab CI but the concepts are the same for any other CI platform.

The idea of this section is to use the SensioLabsInsight SDK into your GitLab CI piepline to make the pipeline fail or succeed depending on the SensioLabsInsight analysis.

Configuring GitLab CI is as easy as creating or editing a .gitlab-ci.yml file at your project's root directory.

1 In SensioLabsInsight, click on My account in the header and go into the API/SDK section. In the Authenticating part, you will see your user UUID and your API token. You will need them to configure GitLab CI, so keep them close.

2 Still on the My account page, go into the Getting the Project UUID section and choose the project you created earlier. Keep its UUID close as you will also need it.

3 In your project, create or edit a .gitlab-ci.yml file at the root of the project. This file will be used by GitLab CI to configure your jobs.

4 In this file, add a job for SensioLabsInsight. You can use the following template:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
image: php:7.1

insight:
    script:
        - curl -o insight.phar -s http://get.insight.sensiolabs.com/insight.phar
        - php insight.phar analyze --no-interaction --no-ansi \
            <project-uuid> \
            --reference=$CI_COMMIT_SHA \
            --user-uuid=<your-user-uuid> \
            --api-token=<your-api-token> \
            --fail-condition="<fail-condition>"

This command will start an analysis on Insight. Here are some explainations about its options:

  • --no-interaction --no-ansi will avoid the CI to fail because of the lack of prompt available
  • --reference=$CI_COMMIT_SHA indicates to SensioLabsInsight to analyze the commit concerned by the job instead of the master branch
  • you should replace <project-uuid> by the project UUID you found in step 2
  • you should replace <your-user-uuid> and <your-api-token> by the credentials you found in step 1
  • <fail-condition> should be replaced by a condition in which the job will fail (for instance counts.critical > 0 or counts.major > 0). You can find all the options in the following section Configure the job failure condition.

5 Commit and push this file on your GitLab instance. A pipeline will be created, the SensioLabsInsight job will trigger an analysis and the status will be computed depending on the fail condition.

Starting from now, each commit and Merge Request created on the project repository will be analyzed and a commit status will be pushed to GitHub.

Configure the job failure condition

You can define your own rules to check if a job should be successful or failed.

Here are all the variables available for your configuration:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# Count by severity
counts.critical
counts.major
counts.minor
counts.info

# Count by category
counts.architecture
counts.bugrisk
counts.codestyle
counts.deadcode
counts.performance
counts.readability
counts.security

# Project grade (none, bronze, silver, gold, platinum)
analysis.grade

# Total violations number
analysis.nbViolations

# Technical debt (in hours)
analysis.remediationCost

While many variables are provided, some configurations are more usual than others. Here are some examples of classical failure conditions:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Fails if there are critical or major violations
counts.critical > 0 or counts.major > 0

# Fails if the grade is too low
analysis.grade in ['none', 'bronze']

# Fails if the project has a lot of violations, including some performance issues
analysis.nbViolations > 50 and counts.performance > 0

# Fails if the technical debt of the project is too high (> 100 hours)
analysis.remediationCost > 100

For instance:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
image: php:7.1

insight:
    script:
        - curl -o insight.phar -s http://get.insight.sensiolabs.com/insight.phar
        - php insight.phar analyze --no-interaction --no-ansi \
            <project-uuid> \
            --reference=$CI_COMMIT_SHA \
            --user-uuid=<your-user-uuid> \
            --api-token=<your-api-token> \
            --fail-condition="counts.critical > 0 or counts.major > 0"