Integrating Sigrid CI with Mendix QSM on Azure Devops
Please note: QSM is the brand name used by Mendix, in this manual we will use Sigrid.
Prerequisites
- You are not using the default Mendix teamserver, but you are using your own Git server for version control of your projects.
- You would like to trigger the Sigrid analysis from within your own pipeline in Git.
- Your runners are able to pull this public docker image, the image is used to preprocess the Mendix code before uploading it to Sigrid.
- You have a Sigrid user account.
- You have created an authentication token using Sigrid.
- You have created a Personal access (PAT) token using the Mendix user settings
On-boarding your system to Sigrid
On-boarding is done automatically when you first run Sigrid CI. As long as you have a valid token, you will receive the message system has been on-boarded to Sigrid. Subsequent runs will then be visible in both your CI environment and sigrid-says.com.
Configuration
Step 1: Create pipeline configuration file for Azure Devops**
We will create a pipeline that consists of two jobs:
- One job that will publish the main branch to sigrid-says.com after every commit to main.
- One job to provide feedback on pull requests, which can be used as input for code reviews.
The recommended approach is to run Sigrid CI using the Docker image published by SIG. In the root of your repository, create a file azure-devops-pipeline.yaml and add the following contents:
stages:
- stage: Report
jobs:
- job: SigridCI
pool:
vmImage: ubuntu-latest
container:
image: softwareimprovementgroup/mendixpreprocessor:latest
options: --user root
continueOnError: true
condition: "ne(variables['Build.SourceBranch'], 'refs/heads/main')"
steps:
- bash: "/usr/local/bin/entrypoint.sh"
env:
MENDIX_TOKEN: $(MENDIX_TOKEN)
MENDIX_SOURCE_DIR: $(System.DefaultWorkingDirectory)
SIGRID_CI_TOKEN: $(SIGRID_CI_TOKEN)
SIGRID_CI_CUSTOMER: <example_customer_name>
SIGRID_CI_SYSTEM: <example_system_name>
continueOnError: true
- job: SigridPublish
pool:
vmImage: ubuntu-latest
container:
image: softwareimprovementgroup/mendixpreprocessor:latest
options: --user root
continueOnError: true
condition: "eq(variables['Build.SourceBranch'], 'refs/heads/main')"
steps:
- bash: "/usr/local/bin/entrypoint.sh"
env:
MENDIX_TOKEN: $(MENDIX_TOKEN)
MENDIX_SOURCE_DIR: $(System.DefaultWorkingDirectory)
SIGRID_CI_TOKEN: $(SIGRID_CI_TOKEN)
SIGRID_CI_CUSTOMER: <example_customer_name>
SIGRID_CI_SYSTEM: <example_system_name>
SIGRID_CI_PUBLISH: 'publishonly'
continueOnError: true
Note the name of the branch, which is main in the example but might be different for your repository. In general, most older projects will use master as their main branch, while more recent projects will use main.
Security note: The options: --user root statement was added deliberately. Based on Microsoft’s documentation, we understand that Linux-based Docker images used in Azure DevOps need to run as root (fifth requirement).
Commit and push this file to the repository, so that Azure DevOps can use this configuration file for your pipeline. If you already have an existing pipeline configuration, simply add these steps to it.
Finally, note that you need to perform this step for every project where you wish to use Sigrid CI. Be aware that you can set a project-specific target quality, you don’t necessarily have to use the same target for every project.
Step 2: Create your Azure DevOps pipeline
In Azure DevOps, access the section “Pipelines” from the main menu. In this example we assume you are using a YAML file to configure your pipeline:
Select the YAML file you created in the previous step:
This will display the contents of the YAML file in the next screen. The final step is to add your account credentials to the pipeline. Click “Variables” in the top right corner. Create a secret named SIGRID_CI_TOKEN and use your Sigrid authentication token as the value.
Add a second secret MENDIX_TOKEN and use the Mendix user settings to create a PAT with ‘mx:modelrepository:repo:read’ access only.
From this point, Sigrid CI will run as part of the pipeline. When the pipeline is triggered depends on the configuration: by default it will run after every commit, but you can also trigger it periodically or run it manually.
Usage
To obtain feedback on your commit, click on the “Sigrid CI” step in the pipeline results screen shown above.
The check will succeed if the code quality meets the specified target, and will fail otherwise. In addition to the simple success/failure indicator, Sigrid CI provides multiple levels of feedback. The first and fastest type of feedback is directly produced in the CI output, as shown in the following screenshot:
The output consists of the following:
- A list of refactoring candidates that were introduced in your merge request. This allows you to understand what quality issues you caused, which in turn allows you to fix them quickly. Note that quality is obviously important, but you are not expected to always fix every single issue. As long as you meet the target, it’s fine.
- An overview of all ratings, compared against the system as a whole. This allows you to check if your changes improved the system, or accidentally made things worse.
- The final conclusion on whether your changes and merge request meet the quality target.
The end of the textual output provides a link to the Sigrid landing page. You can open this URL in order to use Sigrid for interpreting your analysis results.
Whether you should use the text output or the Sigrid page is largely down to personal preference: the text output is faster to access and more concise, while Sigrid allows you to view results in a more visual and interactive way.
Contact and support
Feel free to contact SIG’s support department for any questions or issues you may have after reading this document, or when using Sigrid or Sigrid CI. Users in Europe can also contact us by phone at +31 20 314 0953.