This feature is only available from version 20.7.1.

Overview

This topic provides instructions on how to enable a global repo configuration which will affect all new repositories to be integrated using either WhiteSource for GitHub.com, WhiteSource for GitHub Enterprise, WhiteSource for Bitbucket Server/Data Center, or WhiteSource for GitLab Server. For information on how to migrating existing repositories to the global configuration, see here. Using this global configuration, you will be able to define a configuration template file (repo-config.json), which can be inherited by all future integrated repositories. You will also be able to define a global configuration (not specific to a repository) file (global-config.json) for your integration. The currently-supported global configuration enables you to define how the user onboarding flow will occur for your integrated repositories.

Prerequisites

Ensure that you have already integrated the relevant repository platform with WhiteSource. If needed, refer to the installation sections of the relevant platform below:

Enabling the Global Configuration

(Only for Self-Managed integrations) Create a new organization (GitHub Enterprise), Group (Gitlab Server), or Project (Bitbucket Server/Data Center) named whitesource-config (the name must be exactly as specified here) in your integrated repository platform.
Create a new repository named whitesource-config (the name must be exactly as specified here). In Self-Managed integrations, this repository needs to be inside the whitesource-config entity you created in the previous step.
Add the new whitesource-config repository to your integration. Based on your relevant platform, refer to the correct section:
The whitesource-config repository will now contain a README file and two new configuration files (automatically created by the integration), repo-config.json and global-config.json. Configure these files by referring to the following sections and then continue in this procedure.
Add repositories you want WhiteSource to scan, to your integration.

repo-config.json

This configuration template file is a JSON formatted file that will be applied globally to each newly selected integrated repository. It provides configurable parameters for a WhiteSource scan. All new integrated repositories will inherit the configuration set in this file, unless explicitly overridden by a local .whitesource file in the relevant repository. Refer to the following sections for information on which parameters can be added to the repo-config.json file:

global-config.json

This global configuration file is a JSON-formatted file where you can define global configurations for the integration. The following parameters can be provided:

General Parameters

Parameter

Type

Description

Required

Default

repoConfigMode

String

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

createOnboardingPR - Create an onboarding PR/MR 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/MRs. 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/MR. The integrated repositories will inherit the configuration from the repo-config.json file located inside the whitesource-config repository.

Yes

createOnboardingPR

repoConfigFileName

String

It is possible to rename the .whitesource configuration file added to an integrated repository.

NOTES:

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 the repoConfigMode is set to noWhitesourceFile.

No

.whitesource

branchProtectionRule

Automatically create a “WhiteSource Security Check” branch protection rule for all branches configured by the “baseBrances” property. This will only occur for newly onboarded repositories.

NOTES:

Only valid for the GitHub Enterprise integration.
This will require to add the “Repository administration” to the “Read & Write” permissions to the GitHub application.

{
  "branchProtectionRule": {
    "mode": "newInstallations"
  }
}

No

“none”

Ignored Repos (ignoredRepos)

Parameter	Type	Description	Required	Default
exactNames	Array	Provide a list of specific repositories to ignore from the integration. For example: "ignoredRepos": { "exactNames": ["user/myrepo", "user/testrepo"] }	No	Empty

Account Managment

Parameter

Type

Description

Required

Default

includeOwners->exactNames

Array

Define a whitelist of GitHub Organizations and/or GitHub repository owners who can integrate with the WhiteSource integration.

NOTE: This applies to WhiteSource for GitHub Enterprise and WhiteSource for GitHub.com only.

For example:

"includedOwners": {
  "exactNames": ["MyOrg", "MyUserName"]
}

No

Empty

allowedUserAccounts->exactNames

Array

Provide a way to limit the integration to organization accounts and block all or specific user accounts. If the “exactNames” property is empty all user accounts will be blocked. If the object is missing, no limitation on account type will be enforced.

When a blocked account is trying to install the integration it will be automatically uninstalled.

NOTE: Only valid for the GitHub Enterprise integration.

{
  "allowedUserAccounts": {
    "exactNames": ["userName1", "userName2"]
  }
}

No

Null

Migrating Existing Repositories to the Global Configuration

Performing a migration may slow down the overall responsiveness of the integration. Migration may take a few hours to complete.
For GitHub integrations, when performing a migration on more than 500 repositories, the migration Check Run indicating the status of the migration may not be created due to a GitHub content size limitation.

If you have existing repositories that you want to inherit from the global configuration, do as follows:

Ensure you performed the steps described in Enabling the Global Configuration.
Go to the whitesource-config repository.
Add a new file named migration.json in the default branch.

Inside the file, add the following content (to change parameters and values, refer to the table below):

{
   migrationMode: {
     "changeType": "inheritance",
     "openPR": true
   },
   "includeRepos": [],
   "excludeRepos": []
}

To run the migration, commit and push the file. A WhiteSource Security Check (as part of a Check Run for GitHub.com/GitHub Enterprise, Commit Status for GitLab, and Build Status for Bitbucket Server) will be generated and will display a summary of the migrated repositories. In addition, the migration.json file will be deleted after the migration is completed.
NOTE: In WhiteSource for Bitbucket Server, the migration.json file needs to be manually removed.

migration.json File Parameters

Parameter	Type	Description	Required?	Default
migrationMode.changeType	String	Type of change to perform as part of the migration. There are two possible values: inheritance - The migrating repositories will inherit from the global configuration deletion - The .whitesource file (if found) will be removed from the migrating repositories. Note the following: This should only be used when repoConfigMode in the global-config.json file has the value noWhitesourceFile. Otherwise, no migration will be performed. In WhiteSource for Bitbucket Server, the deletion option is not available. You will need to manually delete the .whitesource file for each migrated repository.	No	inheritance
migrationMode.openPR (WhiteSource for GitHub Enterprise, WhiteSource for GitHub.com, and WhiteSource for Bitbucket Server/Data Center) migrationMode.openMR (WhiteSource for GitLab)	Boolean	Whether an onboarding PR/MR should be created for the migrating repositories. NOTE: When set to false, every migrating repository that currently contains a .whitesource file will trigger an automatic scan after these are migrated. This may affect overall performance of the integration depending on how many migrating repositories you have.	No	true
migrationMode.fixInheritance	Boolean	This parameter can be used in case the Global Configuration repository was moved or renamed since the initial integration. When enabled, the migration will update existing inheritedFrom parameter values in repo-level .whitesource configuration files, to the correct whitesource-config repository.	No	false
migrationMode.triggerScan	Boolean	Control whether the migration should trigger a scan after completion. NOTE: this parameter is relevant only when using migrationMode.changeType=inheritance.	No	true
includeRepos	Array	Provide a list of specific full repository names (owner/repo_name) on which the migration should run. NOTE: You cannot use includeRepos together with excludeRepos as part of a migration. Example: "includeRepos": ["whitesource/unified-agent-distribution", "whitesource/jenkins-whitesource-plugin"]	No	Empty
excludeRepos	Array	Provide a list of specific full repository names (owner/repo_name) on which the migration should not run. NOTE: You cannot use excludeRepos together with includeRepos as part of a migration. Example: "excludeRepos": ["whitesource/unified-agent-distribution"]	No	Empty

Global Repo Configuration