Skip to main content

GitHub Enterprise Server Integration Guide

Overview

The Immersive GitHub Enterprise Server integration allows you to link Immersive content assignments to your GitHub Enterprise Server repositories and include the assignment completion status for individual users in your GitHub Enterprise Server checks. You can configure these checks to be required before merging any code changes. This integration ensures that your teams complete required secure coding and application security training before they are allowed to merge code changes to the selected source code repositories.

We also offer content suggestions for GitHub pull requests and issues based on Common Weakness Enumeration (CWE) references and common phrases associated with code vulnerabilities. Labs are automatically recommended based on code findings, streamlining the remediation of vulnerabilities and enhancing the vulnerability management process. 

Integration Setup

We support integration with GitHub Enterprise Server 3.16.0. Other versions of GitHub Enterprise Server may be able integrate with Immersive successfully, but they haven't been validated by Immersive. 

Permissions

  • Only an organization manager can add, configure, and remove integrations on the platform. This user also needs to be the corresponding GitHub organization's owner in order to register the GitHub app and install it across organizations in the instance.
  • Team managers on the platform can see the installed integrations, but they cannot add, configure, or remove the integrations.
  • Any other users cannot view or manage integrations.

Installing the GitHub Enterprise Server Integration

You can install the GitHub Enterprise Server integration from the Platform Settings area of the Immersive platform.

To install the GitHub Enterprise Server integration:

  1. From the navigation menu, click Manage > Platform Settings, and then click Integrations.

  2. On the Integrations page, under Source Code Management, click GitHub Enterprise Server.
  3. In the Connect to GitHub group, specify the following information:
    • In the GitHub organization field, type the name of the GitHub organization that will manage the Immersive application.

    • In the Instance URL field, type the full URL of your GitHub instance.

      Note: This field will not accept your entry if you include a forward slash (/) at the end of the URL. 

  4. Click Connect to GitHub. 

    The Create GitHub App screen appears. 

  5. On the Create GitHub App screen, you can modify the default GitHub app name if desired. The default name is Immersive.
  6. Click Create GitHub App for Organization Name.

  7. On the Install Immersive screen, select the organization where you want to install Immersive.

  8. Select the repositories that you want to grant access to the Immersive integration:

    • All repositories: Select this option to allow access to all current and future repositories owned by the resource owner. This also includes public repositories (read-only).
    • Only select repositories: Select this option to specify which repositories will be included in the integration. You must select at least one repository.

  9. Click Install. 

You can now see the installed integration on the Immersive platform:

In the Repositories column, you can click the View button to see the integrated GitHub repositories. 

Editing integration settings

To edit your settings to enable or disable features for the GitHub Enterprise Server integration:

  1. On the GitHub Enterprise Server page in the Immersive platform, in the row associated with the organization, click ..., and then click Edit settings.
  2. Toggle the features on or off as desired.
    • The Code access control toggle determines whether or not an option will be available when assigning required content to block code changes in the selected repository if the assignment is not completed by the due date.
    • The Content suggestion toggle determines whether or not the Immersive app suggests relevant content in GitHub Enterprise Server when a vulnerability is mentioned in pull requests or issues. See CWE Content Suggestions.
  3. Close the dialog box. 

Removing an integration

An organization manager can remove an integration, which also removes any associated configuration such as the linked repositories from the platform. The integration must be removed in GitHub Enterprise Server as well. 

To remove the integration:

  1. On the GitHub Enterprise Server page in the Immersive platform, in the row associated with the organization, click ..., and then click Delete. 

  2. On the Delete Integration window, click Delete Integration to uninstall the application for the selected organization. 

  3. Click Disconnect via GitHub to open the Immersive app in GitHub Enterprise Server.

  4. Under the Developer group in the GitHub App, click App settings.

  5. Select the Advanced tab. 

  6. Click Delete GitHub App. 

    The Delete GitHub App? dialog box appears, warning you that this action cannot be undone. 

  7. Type Immersive in the field requesting the name of the GitHub App, and then click I understand the consequences, delete this GitHub App. 

    The Immersive app is deleted from GitHub Enterprise Server. 

Assigning Required Content

Once an organization manager installs the GitHub app as part of the SCM integration setup and enables the integration, an organization or team manager creating or editing an assignment can then select the repositories where an Immersive content completion check should be performed.

Permissions

A team manager or an organization manager can configure an assignment to be required.

Assignment configuration

When creating or editing an assignment on the platform, the team or organization manager can select the option to require the content to be completed before making code changes, as well as select which repositories the check should apply to. 

To do so, when assigning a collection:

  1. In the Set assignment duration group, make sure to specify an End date for the assignment. An end date is required to block merges with an assignment. This is to allow users time to complete the assigned content before blocking their code changes.

  2. In the Associate code repositories group, turn on the Block merges until content completed toggle. 

  3. In the Repositories column, click View.
  4. Click the Add button in the rows for the repositories that you want to add. 

Assignment completion

Once a user whose code changes are blocked due to incomplete required content completes the assignment, any checks that previously failed due to that assignment are retried automatically and will now pass. 

Change Blocking

Once an organization manager installs the GitHub app as part of the SCM integration setup and enables the integration, any new commits pushed to the corresponding GitHub organization will trigger Immersive required assigned content checks.

Initial check run

The initial check for each GitHub user in the organization will fail due to requiring the user to authorize the app to act on their behalf. Users must authorize the app to link their GitHub Enterprise Server account with their Immersive account so the app can locate the status of their required assigned content.

The failed check run output will include a link to authorize the app.

Authorization link

Following the authorization link will present the user with a summary of permissions being requested from the user. Click Authorize Immersive to proceed. 

  • If access is denied, the user will see an error informing them of the issue.
  • If access is granted, the user is returned to the Details page in GitHub Enterprise Server. The check will rerun in the background, which will clear the previous check's status and conclusion and populate it again based on the user's required assigned content completion status (Content complete or Content incomplete). 

Subsequent check runs

Any new check runs triggered after the user authorizes the app will use a cached user access token and associated refresh token to retrieve the user's details for required assigned content checks. The cached access token is valid for 8 hours, and the associated refresh token is valid for 6 months. Once the refresh token expires, or if the user revokes access, the next check run will require the user to reauthorize the app. 

Branch protection rules

In order for the Immersive check to block changes from being merged, customers must include the Immersive check in their branch protection rule configuration.

Repositories on GitHub can be configured to have protected branches. This enables a branch such as main to require certain conditions before merging can take place; for example:

  • A pull request to be made
  • A specified status check to pass

GitHub documentation on branch protection contains more in-depth information, but the steps outlined below give an overview of setting branch protection rules for the Immersive check.

Note: The Immersive check will need to be run at least once for a repository before it can be used for branch protection. This is a limitation on GitHub's end.

Repository settings

Visit the repository page on GitHub GitHub Enterprise Server where you want to set up change blocking.

  1. Navigate to the Settings page.

  2. In the lefthand pane, select the Branches section.

  3. In the Branch protection rules area, click Add rule, or select an existing rule to edit.
  4. Enter a name in the Branch name pattern field.

  5. Select the Require status checks to pass before merging check box. 

  6. At the bottom of the page, click Create or Save changes.

    Your branch protection rule now appears in the Branches section of the repository's settings page:

    Merges against the branches matching the new rule will require the Immersive check to pass:

    The example above also requires pull requests before merging. While this is not necessary, it helps clarify why the merge is blocked.

Content Suggestions

Common Weakness Enumeration (CWE) is a community-developed list of common security weaknesses in software and hardware systems. Each weakness in the list is identified by a unique CWE number and description, providing a standardized way to categorize and describe vulnerabilities and security issues. When integrated into applications, CWE numbers facilitate easier identification, communication, and remediation of security weaknesses in software systems.

When the Content suggestion toggle is turned on for GitHub Enterprise Server, we offer content suggestions for GitHub Enterprise Server pull requests and issues based on CWE references and common phrases associated with code vulnerabilities. The CWE content suggestion feature lets you seamlessly integrate Immersive into your CI/CD pipelines and vulnerability management programs. GitHub Enterprise Server extracts the CWE numbers from SAST/DAST tool comments. 

Labs have a GraphQL API endpoint that enables efficient lab searches via tags. As a result, we automatically recommend labs based on code findings, streamlining the remediation of vulnerabilities and enhancing the vulnerability management process.