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:
   This section lists every webhook event and permission the Mend for GitHub App requires, and what each one is used for. Mend.io follows a least-privilege approach: If something is not listed here, the app does not use it.
   NOTE: Permission fields that are not specified below should be left as is ("No access")

   1. Repository permissions:

      1. Administration: Read-only
         Reads branch protection rules so Mend knows whether its check is a required status check. Read & Write is needed only if you want Mend to manage the branch protection rule itself — this is not the default.

      2. Checks: Read and write
         Publishes scan results as check runs on commits and PRs. Write access is also what allows the re-run button in the Checks UI to reach Mend.

      3. Commit statuses: Read and write
         Used by the remediation engine to post status updates on Mend remediation pull requests.

      4. Contents: Read and write
         Reads your .whitesource configuration and dependency manifests to run the scan. Write access is used to create remediation branches and dependency-upgrade commits.

      5. Custom properties: Read-only
         Reads the custom property values set on a repository, used to map repositories to Mend products.

      6. Issues: Read and write
         Creates and updates vulnerability issues, and posts or edits their comments as findings are resolved.

      7. Metadata: Read-only
         Basic repository information. GitHub requires this for every app and it cannot be disabled. It is also what delivers the Repository event.

      8. Pages: Read and write

      9. Projects: Read and write

      10. Pull requests: Read and write
          Opens remediation pull requests, reads PR contents for PR scans, and posts findings as PR comments.

      11. Webhooks: Read-only

      12. Workflows: Read and write

      13. Not required: Earlier versions of the setup guide asked for the following. Mend makes no API calls to any of them and subscribes to none of their events. If your app grants them, you can safely remove them.

          1. Pages

          2. Projects

          3. Workflows

          4. Deployments

          5. Webhooks

   2. Organization permissions:

      1. Custom properties: Read-only
         Reads organization-level custom property definitions. GitHub also requires this permission in order to deliver the Custom property and Custom property values events.

      2. Members: Read-only
         GitHub requires this permission in order to deliver the Organization event. Mend uses it only to detect organization deletion and clean up the installation — it does not read your member list. GHE only.

      3. Not required: Earlier versions of the setup guide asked for the following. Mend makes no API calls to any of them and subscribes to none of their events. If your app grants them, you can safely remove them.

         1. Pages

         2. Projects

         3. Workflows

         4. Deployments

         5. Webhooks

   3. Webhook events: Subscribe the app to the following events. Each one triggers a specific part of the Mend workflow:

      1. Check run - Lets you re-run a Mend security check directly from the GitHub Checks UI.

      2. Create - Starts branch-aware scanning as soon as a new branch or tag is created.

      3. Custom property - Keeps Mend in sync when the organization-level custom property definitions change.

      4. Custom property values - Maps repositories to Mend products using GitHub repository custom properties.

      5. Installation / Installation repositories - Delivered by GitHub to every app and cannot be turned off. Mend uses them to know which repositories it has access to.

      6. Issue comment - Reads Mend commands typed in issue comments, such as on-demand fix PR requests.

      7. Issues - Tracks the lifecycle of Mend-created security issues and drives remediation from the master issue checkboxes.

      8. Organization - Cleans up the Mend installation automatically if the GitHub organization is deleted. Only the deleted action is used.

      9. Pull request - Runs PR scans on open, update and reopen, and detects when a Mend remediation PR is merged or closed.

      10. Pull request review comment - Handles feedback and remediation commands on SAST findings posted as PR review comments.

      11. Push - Triggers a scan when code is pushed to a tracked branch, and picks up changes to your Mend configuration file.

      12. Release - Triggers a scan when a release is published.

      13. Repository - Core scanning works without it, but repository renames, product mapping and archive state silently drift — leaving stale or duplicate Mend projects. On rename, Mend updates the project to the new repository name; on a topics change, it re-resolves product mapping; on archive or unarchive, it tags the project accordingly. Each of these events also refreshes Mend's cached repository settings and configuration.

      14. Not Required: Earlier versions of the setup guide asked for the following. Mend makes no API calls to any of them and subscribes to none of their events. If your app grants them, you can safely remove them.

          1. Check suite: GitHub automatically delivers check_suite events to any app with write access to Checks, so you may still see them even though the event is not listed above. Mend ignores them — no action is required on your side.

          2. Member

          3. Membership

          4. Team

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

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 API URL value plus '/api/v3' - <https://api.github.com/>/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.

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.