Breadcrumbs

Install Mend for GitHub.com

Overview

Before scanning your repositories with Mend for GitHub.com, you will need to install the Mend for GitHub.com app from the GitHub Marketplace and connect your Mend organization to it.

This article provides installation instructions for Mend for GitHub.com. This article also provides instructions on how to uninstall the app.

Getting It Done

Prerequisites

This step differs between the Mend AppSec Platform and the Legacy SCA application.
The Legacy SCA instructions are listed at the bottom of this section.

Note: Setting up global configuration is recommended.

  • Access to an active Mend Platform organization and a user with organization administrator permissions.

  • The Issues tab must be enabled for each repository. Do as follows for each repository requiring a scan:

    1. Go to the relevant GitHub repository, and click Settings.

    2. Verify that the Issues checkbox is enabled. 

    3. Check that the Issues tab appears next to the Code tab.

  • You must have administrator permissions to your GitHub account and to the relevant repositories (owner credentials) to install the Mend for GitHub.com app.

Prerequisites (Legacy SCA Application)

  • Access to an active Mend SCA organization and be a user with organization administrator permissions.

  • Access to an active Mend SAST organization that is on the same instance as your Mend SCA organization.

    • For example, if your Mend SCA organization is on saas.mend.io, then your Mend SAST organization also needs to be on saas.mend.io.

  • The Issues tab must be enabled for each repository. Do as follows for each repository requiring a scan:

    1. Go to the relevant GitHub repository, and click Settings.

    2. Verify that the Issues checkbox is enabled. 

    3. Check that the Issues tab appears next to the Code tab.

  • You must have administrator permissions to your GitHub organization to install the Mend for GitHub.com app.

  • Mend SCA organizations and GitHub.com organizations are a 1:1 mapping, so you will need to create one Mend SCA organization for every Github.com organization that you wish to integrate

  • If your organization has a limited IP address list, please whitelist the IP addresses listed under “developer-platform”, here.
    NOTE: You can also choose to automatically add Mend IP to your allowed list.

Note: When setting up repository integrations, you can only connect one source code management (SCM) system to a single Mend organization. For example, if you integrate a GitHub organization, you cannot link additional SCM systems like GitLab groups or Bitbucket teams to the same Mend organization.

Install the Mend for GitHub.com app

  1. Navigate to the Mend for GitHub.com app page in the GitHub Marketplace.

  2. Click Install:

    image-20230403-142455.png

  3. If you have multiple organizations, select the organization you wish to install Mend for GitHub.com:

    image-20230403-142437.png

    Otherwise, move to step 4.

  4. Read and select the level of access for the Mend for GitHub.com app:

    • All Repositories (Default): An option to scan all the repositories of the account.

    • Only select repositories: Select specific repositories that you would like to scan.

  5. Click Install:

    image-20230403-142411.png

  6. Read over the requested permissions and select Authorize Mend for GitHub.com:

    image-20230403-144357.png

Permissions and 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")

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

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

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.

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. Pull request - Runs PR scans on open, update and reopen, and detects when a Mend remediation PR is merged or closed.

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

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

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

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

Changing permissions on an existing GitHub App installation requires approval from an organization owner before the change takes effect. Removing any event or permission listed in this page will cause parts of the Mend integration to stop working.

Connect your Mend organization

This step differs between the Mend AppSec Platform and the Legacy SCA application.
The Legacy SCA instructions are listed at the bottom of this section.

After clicking Authorize Mend for GitHub.com you will see a registration form. To fill this out, you will need to obtain your Mend license key.

  1. Within the Mend Application, navigate to Settings (cog icon in the top-right corner) → Integrations.

    image-20240925-125815.png

  2. On the Integrations page, toggle the GitHub.com bar to expand its settings.

  3. Click on Generate Activation Key and copy the value.

    image-20240925-125849.png

Note: The license key is valid for 24 hours. You must generate a new license key if you have not submitted the registration form below within 24 hours.

Note: After you generate the Mend license key, a service user named ws_4_ghc_service_user is created in your Mend organization in the admins group. Do not remove this service user or its permissions as it is required for the Mend GitHub.com integration to function correctly:

image-20230428-212949.png

  1. Now you can fill out the provided registration form to connect your Mend organization:

image-20230403-145522.png

  1. First Name: Your first name

  2. Last Name: Your last name

  3. Email: Your email address

  4. Company: (Optional) Your company name

  5. License Key: Your Mend license key

  6. Country: Your country

  7. Read and check off GitHub’s documents:

    • I agree to the terms of service

    • I agree to the privacy policy

  8. Click on Submit


Connect your Mend organization (Legacy SCA Application)

After you install the Mend for GitHub.com app, there will be a registration form provided to connect your Mend organization. You will need to obtain your Mend license key:

  1. Within your MendSCA application, navigate to the Integrate tab.

  2. On the Integration page, navigate to the Developer Integrations section:

    image-20230403-151211.png

  3. Expand the Developer Integrations section and navigate to Mend for GitHub.com.

  4. Expand the Mend for GitHub.com section.

  5. (SAST only) To enable SAST scanning, connect your MendSAST organization by adding the following value into the SAST Token setting:

    image-20230403-153208.png

    • A service user token. This can be found via your MendSAST organization → Administration → Users → Service Users → Select the “eye” icon next to the desired service user → copy the value. Confirm the selected service user is assigned either the Administrator User Role or Scan Initiation Role.

    • Make sure to Save your SAST Token setting. You will see a “SAST token saved successfully” message when your SAST token is accepted.

  6. Click on Generate License Key and copy the value:

    image-20230403-153536.png

Note: The license key is valid for 24 hours. You must generate a new license key if you have not submitted the registration form below within 24 hours.

Now, you can fill out the provided registration form to connect your Mend organization:

image-20230403-145522.png

  1. First Name: Your first name

  2. Last Name: Your last name

  3. Email: Your email address

  4. Company: (Optional) Your company name

  5. License Key: Your Mend license key

  6. Country: Your country

  7. Read and check off GitHub’s documents:

    • I agree to the terms of service

    • I agree to the privacy policy

  8. Click on Submit

Note: After you generate the Mend license key, a service user named WS_4_GHC_service_user is created in your Mend organization in the admins group. Do not remove this service user or its permissions as it is required for the Mend GitHub.com integration to function correctly:

image-20230403-154222.png
Installing Mend for GitHub.com (Legacy SCA Application)

This video describes the steps to install Mend for GitHub.com if you’re on the Legacy SCA application:

Uninstall Mend for GitHub.com

To uninstall Mend for GitHub.com from your GitHub organization or personal profile:

Uninstall Mend for GitHub.com from your GitHub organization

  1. Within GitHub.com, navigate to Your organizations → select the Settings option of the organization integrated with Mend:

    image-20230403-155113.png

  2. In the left-hand table of contents, find the Third-party Access section and click on GitHub Apps:

    image-20230403-155436.png

  3. Find Mend for GitHub.com and click on Configure:

    image-20230403-155702.png

  4. Scroll down to the Danger zone section and select Uninstall:

    image-20230403-155828.png

Uninstall Mend for GitHub.com from your personal profile

  1. Within GitHub.com, navigate to your Settings section.

  2. In the left-hand table of contents, find the Integrations section and click on Applications:

    image-20230403-161325.png

  3. In the Installed GitHub Apps tab, find Mend for GitHub.com and click on Configure:

    image-20230403-161512.png

    • Optionally, go to the Authorized GitHub Apps tab, find Mend for GitHub.com, and click on Revoke:

      image-20230403-161647.png

  4. On the configuration page, scroll down to the Danger zone section and select Uninstall:

    image-20230403-161217.png