Set up a global configuration for Mend for GitHub Enterprise

Overview

If you are working within an environment that hosts many GitHub Enterprise repositories, Mend for GitHub Enterprise 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 GitHub Enterprise.

How does the global configuration for GitHub Enterprise work?

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 permissions to your GitHub account and to the relevant repositories (owner credentials) in order to create and integrate the relevant repositories.

Setup

Within your GitHub organization, create a new repository named exactly whitesource-config.
Add the new whitesource-config repository to your Mend for GitHub Enterprise integration.
The whitesource-config repository will now contain a README file and the two new configuration files (automatically created by the integration), 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 GitHub Enterprise integration.
1. If you wish to migrate existing integrated repositories to the global configuration, visit our Migrate your existing repositories to Mend for GitHub Enterprise 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

Parameter	Type	Description
settingsInheritedFrom	String	Optional. Default Value: `none`. When the global configuration is enabled, this parameter will specify the location of the whitesource-config repository from which it will inherit its configuration. It must contain the GitHub user name, repository name and branch (optional) of the repo-config.json file location. The default branch is 'master', but can be modified according to the location of the repo-config.json file in the whitesource-config repo. NOTE: You can override specific parameters that are relevant only in the specific repository by adding these after this parameter. Parameters with type of array do not override the value from global configuration, but only add new values. Examples: Using only values defined in the global configuration: `"settingsInheritedFrom": "whitesource-config/whitesource-config@master"` Using values defined in the global configuration and overriding the scan settings parameters: `"settingsInheritedFrom": "whitesource-config/whitesource-config@master", "scanSettings": { "projectToken": "12345", "baseBranches": ["master","integration"] }`
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).
repoConfigFileName	String	Optional. Default Value: `.whitesource`. Rename the .whitesource configuration file added to an integrated repository. Note: This is currently only supported for newly-integrated repositories. If a repository already includes a .whitesource file, the integration will continue using it. This parameter is ignored when repoConfigMode is set to nowhitesourceFile.
enableCustomProductMapping	Boolean	Optional. Default Value: `false`. When set to `true,` each integrated repository that has a topic that starts with the `mendmap-` prefix will be connected to the Product in the Mend Application with the name that goes after the prefix. Note: Topic length limitation is 32 characters.
customPropertyProductMapping	String	Optional. Default Value: `null`. You can set a topic that will define the custom product mapping for this repo using the GitHub repository’s custom properties. In the event of a custom property update, Mend will update the Product/Project information in the Mend Core/Platform. Notes: This feature is supported only for Mend for GitHub Enterprise on a cloud instance. For users who are not creating a new GitHub app but updating the existing one, for this feature to work, you have to make sure to: Add the following permissions to this Mend GHE App: Repository → Custom properties → Read-only Organization → Custom properties → Read-only Add subscription for the following events: Custom property Custom property values Once the above steps are completed, every organization owner on which this app was installed must accept this change for it to take effect. If both this and the parameter `enableCustomProductMapping` are used - only `customPropertyProductMapping` will be used.
CVSSv3	Boolean	Optional. Default Value: `false`. The available parameter values are: true - the `CRITICAL` severity level will be supported for Issues, Checks, and Pull Requests. CVSS score for `CRITICAL` is 9.0-10.0 CVSS score for `HIGH` is 7.0-8.9 false - The highest supported severity level for Issues, Checks, and Pull Requests will be `HIGH` (with CVSS v2 score 7.0-10.0). Notes: From version 22.12.1 (January 2nd, 2022), you must trigger a new scan on a repository to see the `CRITICAL` label for vulnerabilities for existing GitHub Issues created by Mend for GitHub Enterprise. From version 23.5.1 (May 21st, 2023), the parameter CVSSv3 is being deprecated and if it is used - the value will not be read. CVSS v3 with Critical severity is now enabled by default.
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 GitHub Enterprise created GitHub Issues. The format of ignored-vulnerabilities.txt is a list CVEs or WSs IDs separated by a new line: `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.
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. Notes: This parameter has the same functionality as the one in repo-config.json. It was created to address behavior when there is a repo that is not included in the list of repositories that can override the configuration locally, and it contains a .whitesource config file with an invalid format. In this case, there will be a failed Configuration Change Check and further scans will be prevented. With this new implementation, such a case will not happen - the .whitesource file will always be ignored, and Configuration Change Check will not block the scans. If both this and the same parameter in repo-config.json are set up - only global-config.json parameter one will be used.

global-config.json - Ignored Repos (`ignoredRepos`)

Parameter	Type	Description
exactNames	Array	Optional. Default Value: N/A. Provide a list of specific repositories to ignore from the integration. For example: `"ignoredRepos": { "exactNames": ["myorg/myrepo", "myorg/testrepo"] }`

global-config.json - Included Repos (`includedRepos`)

Parameter	Type	Description
exactNames	Array	Optional. Defualt Value: N/A. Provide a list of specific repositories that will be onboarded. For example: `"includedRepos": { "exactNames": ["myorg/myrepo", "myorg/testrepo"] }` 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.

global-config.json - Account Management (`includedOwners`)

Parameter	Type	Description
exactNames	Array	Optional. Default Value: N/A. Define a whitelist of GitHub repository owners that can integrate with the Mend integration. For example: `"includedOwners": { "exactNames": ["MyUserName1", "MyUserName2"] }`
exactNamesFile	Boolean	Optional. Default Value: `false`. The available parameter values are: true - The integration will look for an included-owners.txt file in the root of the whitesource-config repo that defines a whitelist of GitHub repository owners that can integrate with the Mend integration. The format of the included-owners.txt file should be a list of strings delimited by a new line. For example: `UserName1 UserName2 UserName3` false - The integration will not look for a file and will use values listed from the exactNames parameter, if any are provided. Note: If exactNamesFile is set to `true`, but the included-owners.txt does not exist or is empty, the exactNamesFile value will be changed to `false`. If exactNamesFile is set to `true`, the included-owners.txt file contains values, and the exactNames parameter also includes values, values from both parameters will be used.

Parameter

Type

Description

exactNames

Array

Optional. Default Value: N/A. Define a whitelist of GitHub repository owners that can integrate with the Mend integration.

For example:

"includedOwners": {
  "exactNames": ["MyUserName1", "MyUserName2"]
}

exactNamesFile

Boolean

Optional. Default Value: false. The available parameter values are:

true - The integration will look for an included-owners.txt file in the root of the whitesource-config repo that defines a whitelist of GitHub repository owners that can integrate with the Mend integration.

The format of the included-owners.txt file should be a list of strings delimited by a new line. For example:

UserName1
UserName2
UserName3

false - The integration will not look for a file and will use values listed from the exactNames parameter, if any are provided.

Note:

If exactNamesFile is set to true, but the included-owners.txt does not exist or is empty, the exactNamesFile value will be changed to false.
If exactNamesFile is set to true, the included-owners.txt file contains values, and the exactNames parameter also includes values, values from both parameters will be used.

repo-config.json Parameters

Note: The parameters below are exclusive to the repo-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
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. Note: This is a legacy parameter, use `overrideConfigAllowList` in global-config.json instead. If both this and the same parameter in global-config.json are set up - only global-config.json parameter one will be used.

Parameter

Type

Description

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.

Note: This is a legacy parameter, use overrideConfigAllowList in global-config.json instead. If both this and the same parameter in global-config.json are set up - only global-config.json parameter one will be used.

An alternative method for Providing a Global .whitesource Configuration File

NOTE: Supported from version 20.5.1.3 only

You can provide a custom .whitesource configuration file as part of the wss-ghe-app container in order to apply it globally to all of your organization's repositories. Doing so will apply the file to all onboarding pull requests for newly selected repos. Repos that were already selected and activated before this change will not be affected by this global configuration. Only newly onboarded repos will be affected.

To apply this global change, do as follows:

Stop the wss-ghe-app container.
In the wss-ghe-app/conf folder, add your custom .whitesource file (where the prop.json file is located).
Start the wss-ghe-app container.