Understand Mend for Azure Repos
Overview
Before diving into each scan type of Mend for Azure Repos, it is important to understand the integration fundamentals.
This article provides general knowledge on the building blocks of Mend for Azure Repos and other Azure DevOps settings and actions that apply to the integration.
Reference
Onboarding Pull Request
Once you have installed the Mend for Azure Repos integration, you will see a Pull Request (PR) appear in your integrated repositories. This is also referred to as the Mend for Azure Repos “onboarding PR”:
The “onboarding PR” will contain the .whitesource file, which handles the configuration of your Mend for Azure Repos scan. You can edit the .whitesource file before merging the onboarding PR to ensure that your first scan is configured appropriately for your repository:
This will initiate the installation and start the first scan on your selected repositories. You can define settings (like selected branches) later on in the .whitesource file.
The .whitesource file
The .whitesource file is the Mend configuration file that is added to each repository that is enabled for a scan and provides configurable parameter(s) for the Mend scan. Each scan type (i.e., SCA, IaC) has its own set of parameters.
The .whitesource file is only added in the default branch of the repository. Any configuration change done to this file must be in the repository's default branch.
Below is just one example of how you can set up a .whitesource file:
Note: A .whitesource file placed outside the default branch will be ignored.
{
"scanSettings": {
"configMode": "AUTO",
"configExternalURL": "",
"projectToken": "",
"baseBranches": []
},
"checkRunSettings": {
"displayMode": "diff",
"vulnerableCheckRunConclusionLevel": "failure"
},
"issueSettings": {
"minSeverityLevel": "LOW",
"issueType": "DEPENDENCY"
},
"remediateSettings": {
"workflowRules": {
"enabled": true
}
}
}
Mend for Azure Repos - Initiate a merge policy
A merge policy utilizes the app's integration with Azure Repos Branch Policies. It enables the repository's administrator to approve merging a pull request with 'Failed' commit statuses to a target branch in the repository.
For more information on Checks API, see the Azure DevOps Branch policies and settings documentation page.
Notes:
Mend for Azure Repos integration supports merge policies for PRs created either from a branch in the same repository or originating from a different repository.
In the .whitesource file, the parameter
useMendStatusNames
must be set totrue
underpullRequestStatusSettings
as a required parameter.
Create a branch policy in Azure Repos using Mend checks
To create an Azure project-wide branch policy that will block pull requests to the default branch of each repository when the Mend check fails (using the default Mend configuration):
Within Azure DevOps, navigate to your Azure Project → Project settings:
In the Project settings, navigate to Repo → Repositories:
In the Repositories page, navigate to the Policies tab → Branch Policies section:
Click on the “+” icon in the Branch Policies section.
In the pop-up window, select “Protect the default branch of each repository” for the Branches to protect setting:
Click on Create. This will redirect you to the next configuration page.
Navigate to the Status Checks section → click on the “+” icon:
Configure the “Add status policy” view as follows:
Status to check:
For security vulnerabilities:
Mend/mend-security-check
For license violations:
Mend/mend-license-check
Note: A status policy will need to be created for each status.
Policy requirement: Required
Click on Save to save your configuration.
Make sure that your newly created Status Check policy is enabled.
Congratulations, you’ve successfully created a branch policy using Mend checks!
In collaboration with the default Mend configuration, failed Mend checks will block the associated pull request from being merged into your default branch, resulting in the Complete merge option being greyed out and not clickable:
Bot-user maintenance
Integration
For the Mend integration to work with Azure Repos, it needs to have a PAT created by the user with access to the integrated organizations. Mend for Azure Repos will use this PAT to perform its features (repository scanning, work items and pull requests creation, etc.) on behalf of the user who provided the PAT. We recommend having a separate bot-user created solely for this purpose - this process is described in the installation documentation.
When Mend for Azure Repos receives the PAT of a bot-user it creates Service Hooks in each project of each integrated organization. These hooks are triggers for the actions of code pushes and pull requests creation or updating. They can be found in the Project settings → Service hooks. For each hook, there is a history of actions logged, which is convenient for debugging.
Activity
As noted previously, the bot-user does all actions of the Mend for Azure Repos in the integrated organization. Here are some examples:
Onboarding pull request created by the bot-user:
Work Items created by the bot-user:
Maintenance
The PAT of the bot-user has an expiration date set during its creation. Two weeks before the expiration, an alert work item will be created in each repository with the Mend integration enabled. For integration to continue working correctly, the PAT needs to be updated, which can be done in several ways:
Change the expiration date of the existing PAT
Log in as a bot-user
Open User settings → Personal Access Tokens
Select existing PAT and click on "Edit"
Set the new expiration date and save the token
Create a new PAT
Log in as a bot-user
Open User settings → Personal Access Tokens
Delete the existing PAT
Create a new PAT following these instructions (step 5)
Synchronization
Azure Repos does not provide any triggers for some events. Thus, we need to do a periodical synchronization with integrated organizations to keep up with the changes. There are two ways for synchronization:
Automated - each hour, all projects are synchronized
Manual - you can go to Integrations → Azure Repos in the Mend application and press "Sync Projects"
List of the events that require synchronization:
Bot-user received access to a new organization
A new project was created in the organization
PAT updated
Mend for Azure Repos Scan Types
For more information on specific scan scenarios (i.e., SCA, IaC), visit the respective sections below:
SCA - Scan your open source components (SCA) with Mend for Azure Repos
IaC - Scan your infrastructure as code (IaC) with Mend for Azure Repos