Skip to main content
Skip table of contents

Set up a global configuration for Mend for Bitbucket Data Center

Overview

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

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

Setup

  1. Within your Bitbucket Data Center organization, create a new repository named exactly whitesource-config.

  2. Add the new whitesource-config repository to your Mend for Bitbucket Data Center integration.

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

  4. Add the repositories you wish to scan to the Mend for Bitbucket Data Center integration.

    1. If you wish to migrate existing integrated repositories to the global configuration, visit our Migrate your existing repositories to Mend for Bitbucket Server and Data Center 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

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.

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 Bitbucket Data Center 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:

CODE
"settingsInheritedFrom": "whitesource-config/whitesource-config@master"

Using values defined in the global configuration and overriding the scan settings parameters:

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

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 Bitbucket Data Center Issues created by Mend for Bitbucket Data Center.

  • 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 Bitbucket Data Center created Bitbucket Data Center 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 (ignoredRepos)

Parameter

Type

Description

exactNames

Array

Optional. Default Value: N/A. Provide a list of specific repositories to ignore from the integration. For example:

CODE
"ignoredRepos": {
  "exactNames": ["myorg/myrepo", "myorg/testrepo"]
}
JavaScript errors detected

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

If this problem persists, please contact our support.