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 Integrations Page

Note: This step differs slightly between the Mend AppSec Platform and the Legacy SCA Application. Instructions for the Legacy Application are available at the bottom of this section.

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

1. Navigate to the Integrations page by clicking the cogwheel at the upper right corner of the UI:

   

2. Click the GitHub Enterprise tile under Repositories:
   

   

3. This will take you to the Integrate page, where you are required to fill in 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.

4. 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. 

5. 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

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.