Migrate your existing repositories to Mend for GitHub.com global configuration

Overview

When you set up a global configuration for Mend for GitHub.com, you may have repositories that are already onboarded with the integration that you want to include in the global setup.

This article provides information on how to migrate existing integrated repositories into your global configuration for Mend for GitHub.com.

Use Case

Configuration of the migration occurs via a migration.json file within your whitesource-config repository. To set up your migration, see the Parameters section provided in this documentation. Below are a couple of examples of fine-tuning a migration using a migration.json file:

Example One: A migration.json using the includeRepos setting:

JSON

{
	"migrationMode": {
		"changeType": "inheritance",
		"openPR": true
	},
	"includeRepos": ["githuborganization/repo1","githuborganization/repo2"]
}

Example Two: A migration.json using the excludeRepos setting:

JSON

{
	"migrationMode": {
		"changeType": "inheritance",
		"openPR": true
	},
	"excludeRepos": ["githuborganization/repo3","githuborganization/repo4"]
}

Getting It Done

Performing a migration may slow down the overall responsiveness of the integration. The migration may take a few hours to complete. 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.

Prerequisites

Ensure you have performed the steps described in setting up the global configuration.
You must have administrator permissions to your GitHub account and to the relevant repositories (owner credentials).

Start the migration

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

Go to the whitesource-config repository.
Add a migration.json file that includes its parameters to the whitesource-config repository’s default branch.
Commit and push the migration.json file to start the migration.

View the migration status

A Mend Security Check will be generated and display a summary of the migrated repositories.

View the migration results

A Mend Security Check will be generated and display a summary of the migrated repositories. In addition, the migration.json file will be deleted after the migration is completed.

Reference

Parameters

migration.json - General Parameters

Parameter

Type

Description

includeRepos

Array

Optional. Default Value: N/A. Provide a list of specific full repository names (owner/repo_name) on which the migration should run.

Example:

CODE

"includeRepos": ["whitesource/unified-agent-distribution", "whitesource/jenkins-whitesource-plugin"]

Note: You cannot use includeRepos together with excludeRepos as part of a migration.

excludeRepos

Array

Optional. Default Value: N/A. Provide a list of specific full repository names (owner/repo_name) on which the migration should not run.

Example:

CODE

"excludeRepos": ["whitesource/unified-agent-distribution"]

Note: You cannot use excludeRepos together with includeRepos as part of a migration.

migration.json - Migration Mode (`migrationMode`)

Parameter

Type

Description

changeType

String

Optional. Default Value: inheritance. Type of change to perform as part of the migration.

There are three 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: deletion should only be used when repoConfigMode in the global-config.json file has the value nowhitesourceFile. Otherwise, no migration will be performed.

fixInheritance - The migration will update existing settingsinheritedFrom parameter values in repo-level .whitesource files to the correct whitesource-config repository.

Note: fixInheritance can be used in case the Global Configuration repository was moved or renamed since the initial integration.

openPR

Boolean

Optional. Default Value: true. Whether an onboarding PR 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.

triggerScan