Versions Compared


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


  1. Navigate to the 'Integrate' page of the WhiteSource application. Expand the 'WhiteSource for GitHub Enterprise' bar to view the following fields:

    1. GitHub URL: Your GitHub Enterprise instance Destination URL. For example:

    2. GitHub API URL: The GitHub URL value plus '/api/v3' - <GitHub URL>/api/v3

    3. GitHub application id: From the GitHub Enterprise server UI, go to Settings > Organization Settings > WhiteSource > GitHub Apps. Click Edit next to the GHE icon. Scroll to the About section. Copy the GitHub ID value and paste it as the GitHub application id input field value.
      Leave this page open in Edit mode, as you will need it for the next field (Github webhook secret).

    4. Github webhook secret: Paste the webhook secret that you generated as part of the Install the GitHub Application step.

    5. GitHub application private key: In the Private key section, click Generate private key. Save the private_key.pem file that is generated. Open this file in any editor and copy its contents. Paste the contents in the GitHub application private key input field. NOTE: The key is encrypted and its value is not revealed to WhiteSource.

  2. Click on Get Activation Key to generate your activation key. A new Service user is created for this integration inside the WhiteSource Application with a WS prefix.  NOTE: Do not remove this Service user and ensure this user remains part of the Admin group. 

  3. Copy the generated Activation Key to the clipboard. You will need to use it in the next section.


  1. Open the file index.html located inside the wss-configuration directory via a Chrome or Firefox Web browser. The WhiteSource Configuration Editor page is displayed.

  2. Load the template JSON configuration file by clicking Choose File button and selecting the file located at wss-configuration/config/prop.json. The General tab appears in the Editor.

  3. Click the General tab and enter the Activation Key which you copied in the previous section.

  4. To display the Proxy tab, click the Advanced Properties checkbox on the Home tab.  Proxy fields that are not mandatory (e.g., user name and password) must be left blank.

  5. Click Export, and save the JSON file with the name prop.json. This file will be used in the next sections.



Global Settings








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.


Using only values defined in the global configuration:

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

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

Code Block
"settingsInheritedFrom": "whitesource/whitesource-config@master", 
"scanSettings": {
  "projectToken": "12345",
  "baseBranches": ["master","integration"]




  1. Stop the wss-ghe-app container.

  2. In the "wss-ghe-app/conf" folder, add your custom “.whitesource” file (where the prop.json file is located).

  3. Start the  wss-ghe-app container.

Configuration Error Issues

Will alert the user on configuration errors that affects their scan by creating a configuration error issue and check run. In case of such an error the following will occur:

  1. Stop the workflow. Do not create a scan or the WhiteSource Security check run.

  2. Create a “Configuration Failed” check run.

  3. For each config file that failed parsing - create a new type of issue, titled Action Required: Fix WhiteSource Configuration File - {fileName}. If the error originated from the repo-config.json or global-config.json files, then the issue will be created in the whitesource-config repo.

Handled errors:

  1. Error parsing the configuration files (.whitesource/repo-config.json/global-config.json json)

Initiating a Scan

A WhiteSource scan is initiated via a valid GitHub push command . A valid push command meets at least one of the following requirements:

  • One of the commits in the push command added/removed a source file(s) that has an extension supported by WhiteSource.
    Refer to the WhiteSource Languages page in order to find out whether or not a specific language and its extensions are supported. 

  • One of the commits in the push command includes an addition/modification of the package manager dependency file(s).
    Refer to the list of supported dependency files to find out whether your dependency files are supported.

NOTE: a push command may consist of multiple commits.


  1. Get the latest WhiteSource for GitHub Enterprise version from WhiteSource Support.

  2. Build these three Docker images from the new version - see here.

    • wss-ghe-app

    • wss-scanner

    • remediate-server

  3. Stop currently-running Docker containers from the previous version:

    Code Block
    docker stop <wss-ghe-app> <wss-scanner> <remediate-server>

  4. Remove the Docker containers from the previous version:

    Code Block
    docker rm <wss-ghe-app> <wss-scanner> <remediate-server>

  5. Fetch the activation key from the existing prop.json file (the propertyValue associated to the property "bolt.op.activation.key") and copy it to the clipboard.

  6. Generate and save the new prop.json file by following the steps here and using the activation key value that was just copied. 

  7. Run the containers - see here.

  8. (Optional) If the new wss-ghe-app container has a different URL than the previous container, then follow the guidelines here to update the GitHub App webhook URL.