The aim of this document is to fully setup the SymfonyInsight integration of a Symfony bundle hosted on Bitbucket (bitbucket.org).
SymfonyInsight does not offer native support Bitbucket commit statuses. However, we will achieve in this document a similar result using the Insight SDK in your Continuous Integration platform (for instance Bitbucket Pipeline or Bamboo).
Click on the
Add project link located at the top of the right sidebar
of your SymfonyInsight dashboard and on the
Optionally, the first time you try to analyze Bitbucket projects, you'll
be redirected to the Bitbucket website, where you can authorize SensioLabs to access
to your repositories by clicking the
Grant access button.
This is necessary for SymfonyInsight to access the source code of your project. If at some point you want to revoke access for SymfonyInsight, go to the Oauth section of your personal profile and click on the Revoke link.
After the previous optional redirection, SymfonyInsight will show you the list of your projects hosted at Bitbucket, both public and private. When a project is private, SymfonyInsight will display a lock icon next to its name.
For performance reasons, this list is limited to 100 different projects for each of the GitHub organizations that you belong to.
Select a project to analyze and choose the
Symfony bundle project type to enable
the rules for Symfony bundles.
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 pull request to ensure the code quality is not decreasing along the project lifetime.
To integrate SymfonyInsight into Bitbucket pull requests, you will need a Continuous Integration platform configured on repository. If you don't have one, you can use Bitbucket Pipelines.
This section will use Bitbucket Pipelines but the concepts are the same for any other CI platform.
The idea of this section is to use the SymfonyInsight SDK into your Bitbucket Pipelines piepline to make the pipeline fail or succeed depending on the SymfonyInsight analysis.
Configuring GitLab CI is as easy as creating or editing a
bitbucket-pipelines.yml file at your
project's root directory.
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 Bitbucket Pipelines, so keep them close.
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.
In your project, create or edit a
bitbucket-pipelines.yml file at the root of the project.
This file will be used by Bitbucket Pipelines to configure your jobs.
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 12 13
image: php:7.4 pipelines: default: - step: script: - curl -o insight.phar -s https://get.insight.symfony.com/insight.phar - php insight.phar analyze --no-interaction --no-ansi \ <project-uuid> \ --reference=$BITBUCKET_COMMIT \ --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 explanations about its options:
--no-interaction --no-ansiwill avoid the CI to fail because of the lack of prompt available
--reference=$BITBUCKET_COMMITindicates to SymfonyInsight 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-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.
Commit and push this file on Bitbucket. 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 pull request created on the project repository will be analyzed and a commit status will be pushed to Bitbucket.
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 12 13
image: php:7.4 pipelines: default: - step: script: - curl -o insight.phar -s https://get.insight.symfony.com/insight.phar - php insight.phar analyze --no-interaction --no-ansi \ <project-uuid> \ --reference=$BITBUCKET_COMMIT \ --user-uuid=<your-user-uuid> \ --api-token=<your-api-token> \ --fail-condition="counts.critical > 0 or counts.major > 0"