Set up a global configuration for Mend for Azure Repos

Overview

If you are working within an environment that hosts many Git repositories, Mend for Azure Repos provides a global configuration solution to apply parameters to multiple repositories with ease.

This article provides details and instructions on how to create and enable a global configuration that will affect all new repositories integrated using Mend for Azure Repos.

Use case

Using the global configuration, you are able to define a configuration that can be inherited by all future integrated repositories, as well as define an onboarding configuration for your integration. The three components of the global configuration are:

whitesource-config repository: The repository where your global-config.json and repo-config.json files are located. Integrated repositories' .whitesource files can point to this repository to inherit the configurations it houses.
global-config.json file: A JSON formatted configuration file where you can define how the onboarding flow will occur for your integrated repositories.
repo-config.json file: A JSON formatted configuration file that will be applied globally to each newly selected integrated repository. It is the global equivalent of the .whitesource file and provides the same configurable parameters for a Mend scan, organization-wide.

Note: All newly integrated repositories will inherit the configuration set in repo-config.json, unless explicitly overridden by a local .whitesource file in the relevant repository.

Getting it done

Prerequisites

You must have administrator privileges to your Azure DevOps Repos account and to the relevant repositories (owner credentials) in order to create and integrate the relevant repositories.
You have successfully installed Mend for Azure Repos following the instructions in our Install Mend for Azure Repos documentation.

Global Configuration Levels

Mend for Azure Repos supports two levels of global configuration due to Azure Repo's architectural design:

Azure Organization level configuration - Using the “whitesource-config” Azure project / “whitesource-config” repo. Configuration at this level will affect all projects integrated using Mend for Azure Repos.
Azure Project level configuration - Using the "YourProjectName" Azure project / “whitesource-config” repo. Configuration at this level will also affect projects integrated using Mend for Azure Repos but can be customized separately.

Note that configurations can be overridden depending on where they are placed:

.whitesource configuration (at the local repo level, aka the "integrated repo/repo to be scanned") will override the "top" and "middle" levels mentioned above.
repo-config.json configuration at the "middle" level will override whatever is set at the "top" level mentioned above, but will be overridden by the .whitesource file at the integrated repo level.

Setup

1. For Azure Organization level global configuration: Within your Azure DevOps Repos organization, create a new project named exactly “whitesource-config”.
2. For Azure Project level global configuration: Within your Azure DevOps Repos project, create a new repository named exactly “whitesource-config”.
Sync your Azure project by going into your Mend UI → Integrate tab → Developer Integrations → Mend for Azure Repos → Sync Projects.

Notes:

This will kick off the integration to check if there are any new repos that need to be onboarded (this being the "whitesource-config" repo you created in step 1).
To learn more about the synchronization process, please refer to the synchronization process.

The whitesource-config repository will now contain a README file and the two new configuration files (automatically created by the integration once the synchronization process is completed), repo-config.json and global-config.json. Configure these files with the Parameters provided in this documentation.
Add the repositories you wish to scan to the Mend for Azure Repos integration.
1. If you wish to migrate existing integrated repositories to the global configuration, visit our Migrate your existing repositories to Mend for Azure Repos global configuration documentation.

Note: The whitesource-config repository does not support changes to the configuration files done via pull requests. Any edits must be committed directly to the default branch of the repository. Due to this, branch protection rules should not be applied to the whitesource-config repository.

Reference

Parameters

global-config.json General Parameters

Note: The parameters below are exclusive to the global-config.json file. The configuration parameters of the .whitesource file can be applied in the repo-config.json as well, but to be used globally.

Parameter

Type

Description

repoConfigMode

String

Required. Default Value: createOnboardingPR. The configuration mode to be used on all integrated repositories. There are three options:

createOnboardingPR - Create an onboarding pull request (PR) containing a .whitesource file with inherited configuration.
- The integrated repositories will inherit the configuration from the repo-config.json file located inside the whitesource-config repository.
- The .whitesource configuration file generated in each repository will contain a single parameter, settingsInheritedFrom, with a value pointing to the repo name and branch in which the repo-config.json file is located.
pushwhitesourceFile - A .whitesource configuration file with inherited configuration will immediately be pushed to the default branch of all integrated repositories without creating any onboarding PRs.
- The .whitesource configuration file generated in each repository will contain a single parameter, settingsInheritedFrom, with a value pointing to the repo name and branch in which the repo-config.json file is located.
nowhitesourceFile - Integrated repositories will be scanned without creating a .whitesource file or onboarding PR. The integrated repositories will inherit the configuration from the repo-config.json file located inside the whitesource-config repository.

Note: If the nowhitesourceFile parameter is set, the existing repositories that Mend has access to require a valid commit before scanning will continue. Newly created repositories that Mend has access to will automatically start the initial scan (versus waiting for the onboarding PR to be merged when createOnboardingPR is set).

overrideConfigAllowList

Array

Optional. Default Value: null. Regulate the ability of repositories that inherit their configuration from the whitesource-config repository to override the parameters locally. There are three options:

null ("overrideConfigAllowList": null) - All repositories that inherit configuration from this repo-config.json file can override its settings locally in their .whitesource file.
Empty array ("overrideConfigAllowList": []) - All repositories that inherit configuration from this repo-config.json file cannot override its settings in their .whitesource file.
Array with values ("overrideConfigAllowList": ["orgName1/repoName1", "orgName2/repoName2"]) - Only the repositories specified in this list that inherit configuration from this repo-config.json file can override its settings locally in their .whitesource file.

global-config.json - azureReposSettings

Note: When the configuration for the workitemType or customFields parameters is changed, all Mend-created work items will be updated after a valid push in the repository.

Parameter

Type

Description

workItemType

String

Optional. This parameter specifies the type of work item to be created for all Mend work items. Set this parameter to a string equal to the name of a work item type in your project.

Note:

Using a non-existent work item type will prevent the creation or update of work items for vulnerabilities, licensing, or IaC.
If the specified work item type has any required fields, they must be specified with the customFields parameter in order for work items to be created or updated
If there are problems in the configuration and Mend fails to create/update work items properly there will be created a configuration error work item with a message about this.
The “Description" field for work items is required. If this “Description" field is missing from the work item type, the integration result details (CVE details) will not be provided in the work item.

Defualt Value depends on the process type:

Basic - Issue
Agile - Issue
CMMI - Issue
Scrum - Impediment

customFields

Object

Optional. Defualt Value: null. This parameter specifies custom fields to be added to all Mend work items.

If a field with a matching name exists in the work item template and the value is a compatible data type, it will be added to the work item.

Example of use:

CODE

“azureReposSettings”:{
  “workItemType”: “Custom Work Item”,
  “customFields”: {
    “Priority”: 2,
    “Assigned To” : “john.doe@mail.com”,
    "Team" : "Blue",
    “Mend Detected Vulnerabilities” : "mend.description"
  }
}

Note:

This parameter can also be set per repository within the .whitesource file. Read more here: Mend SCA for Azure Repos - Issue Settings (issueSettings) or Mend IaC for Azure Repos - Issue Settings (issueSettings).
- If configurations exists both at the global and local repository levels, the local repository configuration (.whitesource file) takes precedence.
This parameter must include all required fields for the specified workItemType in order to create or update work items for vulnerabilities, licensing, or IaC.
The customFields parameter can be used to specify a custom Work Item field where the vulnerability description ("mend.description") will be populated in instead of the default "Description" Azure Work Item field. When creating this custom field, the Type must be Text (multiple lines). In the example above, the custom field for this is "Mend Detected Vulnerabilities".

ignoreSpecificVulnerabilities

Boolean

Optional. Default Value: false. When set to true, all vulnerability IDs listed in a created ignored-vulnerabilities.txt file in the root of whitesource-config repository will be ignored during SCA security scans. The vulnerabilities:

Will not be mentioned in nor fail the Mend Security Check.
Will not be mentioned in Mend for Azure DevOps Issues.

The format of ignored-vulnerabilities.txt is a list CVEs or WSs IDs separated by a new line:

CODE

CVE-2017-1000048
WS-2014-0005
CVE-2014-6394

Note:

Existing mentions of the ignored vulnerabilities will be removed from the issues with the next valid push after this parameter is enabeled.
These change affects only Repo Integration and doesn’t change the vulnerability alerts in the Mend SCA Application.

global-config.json - Ignored Repos

Parameter	Type	Description
exactNames	Array	Optional. Defualt Value: `null`. Provide a list of specific repositories to ignore from the integration. For example: CODE `"ignoredRepos": { "exactNames": ["Azure_Project_Name1/Repo_Name", "Azure_Project_Name2/Repo_Name"] }`

global-config.json - Included Repos

Parameter	Type	Description
exactNames	Array	Optional. Defualt Value: `null`. Provide a list of specific repositories that will be onboarded. For example: CODE `"includedRepos": { "exactNames": ["project1/repo1", "project2/repo2"] }` Notes: If parameter includedRepos is set to `null` then all repositories will be onboarded: `"includedRepos": null`. This parameter shouldn’t be used together with ignoredRepos. Scenario of both parameters used in one configuration is unsupported and may lead to unexpected results. When adding a new repository that was not previously included in the exactNames list, the creation of the repository's onboarding pull request will occur only after a valid push event happens in the repository (Given that the app was provided access to this repository in the SCM, otherwise the onboarding process will not take place). This parameter will not override settings in SCMs where it is possible to control access to repositories for the installed integration. This means that if you excluded some repositories from access for Mend, they will not be scanned even if these repositories are mentioned in this parameter.