Skip to main content
Skip table of contents

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.

CODE
{
  "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 to true under pullRequestStatusSettings 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):

  1. Within Azure DevOps, navigate to your Azure Project → Project settings:

  2. In the Project settings, navigate to RepoRepositories:

  3. In the Repositories page, navigate to the Policies tab → Branch Policies section:

  4. Click on the “+” icon in the Branch Policies section.

  5. In the pop-up window, select “Protect the default branch of each repository” for the Branches to protect setting:

  6. Click on Create. This will redirect you to the next configuration page.

  7. Navigate to the Status Checks section → click on the “+” icon:

  8. Configure the “Add status policy” view as follows:

    1. 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.

    2. Policy requirement: Required

  9. Click on Save to save your configuration.

  10. 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"

image-20240311-135415.png

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:

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.