Skip to main content
Skip table of contents

Create the Mend for GitHub Enterprise App

Overview

This article provides step-by-step instructions for creating the Mend for GitHub Enterprise App in your GitHub Enterprise Environment.

Getting It Done

Creating the Mend for GitHub Enterprise App

  1. Go to your GitHub Enterprise instance, select Settings > Organization, and then within the Organization Settings, select GitHub Apps from the Developer settings

  2. Click the New GitHub app button

  3. Enter your GitHub Enterprise password

  4. The Register new GitHub App page is displayed

  5. Fill in the fields according to these guidelines in steps 6 and 7

  6. General:

    1. GitHub App name: “Mend App”. NOTE: The name cannot contain an underscore (“__”)

    2. Description: Mend for GitHub Enterprise

    3. Homepage URL: https://mend.io

    4. User authorization callback URL: empty

    5. Setup URL (optional): empty

    6. Webhook URL: A valid URL pattern. This is a temporary value that is changed at a later stage of the installation process

    7. Webhook secret: Generate and enter a secret value (string) and make sure you copy this value somewhere. You will need it for later

  7. Permissions & events:
    NOTE: Permission fields that are not specified below should be left as is ("No access")

    1. Repository permissions:

      1. Administration: Read-only

      2. Checks: Read and write

      3. Commit statuses: Read and write

      4. Contents: Read and write

      5. Custom properties: Read-only

      6. Deployments: Read-only

      7. Issues: Read and write

      8. Metadata: Read-only

      9. Pages: Read and write

      10. Projects: Read and write

      11. Pull requests: Read and write

      12. Webhooks: Read-only

      13. Workflows: Read and write

    2. Organization permissions:

      1. Custom properties: Read-only

      2. Members: Read-only

      3. Projects: Read and write

      4. Webhooks: Read-only

    3. Subscribe to events: Select the following events:

      1. Check run

      2. Create

      3. Custom property

      4. Custom property values

      5. Check suite

      6. Issues

      7. Member

      8. Membership

      9. Organization

      10. Pull request

      11. Pull request review comment

      12. Push

      13. Repository

        • This event is optional, subscribing to it will enable a feature that will add repoArchived Project tag in the Mend Application for the repositories that were archived.

      14. Team

      15. Team add

  8. Where can this GitHub App be installed? It is recommended to select 'Any account', so that any GitHub Organization can install this App. Alternatively, you can limit it to your own organization

  9. Click the Create GitHub App button

  10. (Optional) Edit the GitHub App and upload a logo for your App

Fill in fields on the Mend Platform Integrations Page

Open a separate browser tab or window and log in to the Mend Platform.

  1. Navigate to the Integrate page of the Mend Platform by clicking the cog in the upper right corner.

  2. Enable the Mend for GitHub Enterprise integration by clicking the toggle switch to view the following fields:

    1. GitHub URL: Your GitHub Enterprise instance Destination URL. For example: https://GitHubEnterprisedev.com.

    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 > GitHub Apps. Click Edit next to the Github app you created previously. 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 of the Mend App Settings, 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 Mend.

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

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

Configuring Deployment Settings

Run the UI configuration tool from the wss-configuration Directory

The UI Configuration tool enables you to configure the deployment file according to your specific configuration requirements. 

  1. Open the file index.html located inside the wss-configuration directory via a Chrome or Firefox Web browser. The Mend 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.

Notes:

  • You can export the JSON file at any time, even if you did not finish editing it in order to save your configurations and to enable assigning the configuration of a specific section to the appropriate professional in your organization (e.g., data source section may be assigned to the DBA of your organization).

  • When exporting the configuration file, it is important to give it the filename "prop.json".

  • In case of replacing the prop.json file with a new one, it is not enough to restart the controller and scanner pods. It is required to delete the old pods and run new ones.

  • If using the WS_ACTIVATION_KEY environment variable, the activation key did not require to be passed through the prop.json file.

Reference

Details on Attributes of the Configuration File

Section

Label

Name

Type

Mandatory

Description

Sample Value

General

Activation Key

bolt.op.activation.key

String

yes

Your generated activation key in the Mend application

Proxy

HTTP Proxy Host

proxy.host

Host Address

no

HTTP proxy host. Leave blank to disable. Default value: Empty

Proxy

HTTP Proxy Port

proxy.port

Integer

no

HTTP proxy port. Leave blank to disable. Default value: Empty

Proxy

Proxy User

proxy.user

String

no

Proxy UserName (if applicable)

user

Proxy

Proxy Password

proxy.password

String

no

Proxy Password (if applicable)

abc123

Proxy

Enable Proxy For All Traffic

proxy.for.all

Boolean

no

If set to false (default), only the calls that the Controller and Scanner do to the Mend Core application will be sent through the proxy. If set to true, all traffic of the Controller and Scanner will be sent through the proxy.

NOTES:

  • For this parameter to work, environment variable WS_GIT_CONNECTOR must be set to true in the Scanner.

  • Proxy will also be used for the Unified Agent in the Scanner. To control proxy for the Unified Agent separately (via Proxy Settings in whitesource.config configuration file), set the environment variable MEND_PROXY_FOR_UA to false in the Scanner.

  • Supported from version 22.9.1

Advanced

Controller URL

controller.url

String

no

The ability to modify the App container URL in case its default name (wss-ghe-app) was modified. Default value: http://wss-ghe-app:5678

http://wss-ghe-app:5678

Issues

Should Create Issues

bolt4scm.create.issues

Boolean

no

The ability to globally enable/disable Issues creation across all of your organization's repositories. Default value: true 
(NOTE: Supported from version 20.5.1.3 only)

Issues

Should Create Build Status

bolt4scm.create.check.runs

Boolean

no

The ability to globally enable/disable build statuses across all of your organization's repositories. Default value: true 
(NOTE: Supported from version 20.5.1.3 only)

Next Steps after creating the Mend for GitHub Enterprise App

After you have successfully created the Mend for GitHub Enterprise App in your GitHub Enterprise environment, you are ready to build and deploy the Mend for GitHub Enterprise containers.

JavaScript errors detected

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

If this problem persists, please contact our support.