While SymfonyInsight main expertise is on Symfony, SymfonyInsight is also used by many Drupal modules developers to ensure high quality coding standards. SymfonyInsight 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 SymfonyInsight integration of a Drupal module hosted on a GitLab instance (GitLab.com or a custom GitLab).
This document considers that your GitLab repository is accessible by SymfonyInsight. If it is not, referer to the corresponding section "Analyze projects not accessible by SymfonyInsight".
SymfonyInsight 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).
1 Before adding your project on SymfonyInsight, you need to obtain the SSH key SymfonyInsight 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
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
3 In SymfonyInsight, 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:
Drupal module project type to enable the rules for Drupal modules.
Finally, click on the
Analyze button and SymfonyInsight will start the analysis
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.
To integrate SymfonyInsight 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 SymfonyInsight SDK into your GitLab CI piepline to make the pipeline fail or succeed depending on the SymfonyInsight analysis.
Configuring GitLab CI is as easy as creating or editing a
.gitlab-ci.yml file at your
project's root directory.
1 In SymfonyInsight, 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 SymfonyInsight. 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 https://get.insight.symfony.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-ansiwill avoid the CI to fail because of the lack of prompt available
--reference=$CI_COMMIT_SHAindicates to SymfonyInsight to analyze the commit concerned by the job instead of the master branch
<project-uuid>by the project UUID you found in step 2
<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 SymfonyInsight 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.
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
1 2 3 4 5 6 7 8 9 10 11
image: php:7.1 insight: script: - curl -o insight.phar -s https://get.insight.symfony.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"