Versions Compared

Old Version 59

changes.mady.by.user Vital Batyr

Saved on

compared with

New Version 60

changes.mady.by.user Michelle Friedman

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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:

  1. Only valid for the GitHub Enterprise integration.

  2. This will require to add the “Repository administration” to the “Read & Write” permissions to the GitHub application.

Code Block
{
  "branchProtectionRule": {
    "mode": "newInstallations"
  }
}

No

“none”

settingsInheritedFrom

Add an option for a regular account repo-settings.json or global-settings.json file to inherit settings from the

“whitesource

whitesource-

config”

config account’s global-settings.json file. For example, a global-config.json file in {someOrg}/whitesource-config could inherit settings from the whitesource-config/whitesource-config file.

If this parameter is enabled, after creating a whitesource-config file inside the repos of the given organization, it will be automatically populated with the settings from the whitesource-config/whitesource-config file.

NOTE: You can override specific parameters that are relevant only in the specific repository by adding these after this parameter.

Examples:

Using only values defined in the global configuration:

Code Block
"settingsInheritedFrom": "whitesource-config/whitesource-config@master"

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

Code Block
"settingsInheritedFrom": "whitesource-config/whitesource-config@master", 
 "issueSettings": {
    "minSeverityLevel": "MEDIUM"
  }

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:

Code Block
"ignoredRepos": {
  "exactNames": ["user/myrepo", "user/testrepo"]
}

No

Empty

Account Managment

Parameter 

Type

Description

Required 

Default

includedOwners->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:

Code Block
"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.

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

No

Null

Manually Triggering Repository Scans

...

For each repository in the list, a scan will be triggered (in the latest commit of the specified branch), including the creation of the security check run.

Manual scan logs

When triggering a manual scan it is possible to save the scan logs as a single zip file to a dedicated repository: whitesource-config/ws-logs. To enable this functionality additional flag should be added to the scan.json, uploadScannerLogs set to true.

Example:

Code Block
{
  "repositories": [
    {
      "fullName": "orgName1/repoName1",
      "branchName": "main",
      "uploadScannerLogs": true
    }
  ]
}

NOTE:

  • Name of the zip file: scanner_logs_{SCAN_TOKEN}.zip

  • The name of the ws-logs repo is configurable using the env var WS_LOG_REPO_NAME

  • If that repo whitesource-config/ws-logs does not exist - then the manual scan will not run, and there will be a check run explaining why:

    Image Added

Migrating Existing Repositories to the Global Configuration

...

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:

Code Block
"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:

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

No

Empty