Adding GitHub integration

You can integrate LGTM Enterprise with GitHub.com and GitHub Enterprise. This allows users to log in to LGTM using their GitHub account, and can also be configured to enable LGTM to analyze repositories hosted by GitHub.

For details of other available integrations, see Defining integrations with external systems.

Overview

To set up this integration you need to enter information into the administration pages of both systems (GitHub and LGTM). In the following procedure you will:

  • Start defining a new integration in LGTM.

  • Log into either GitHub.com or GitHub Enterprise and register LGTM Enterprise as a GitHub App.

  • Copy information from GitHub to LGTM to complete the process.

  • Make sure LGTM's external URL is resolvable from your worker host machines. For more information, see Setting LGTM's external URL.

  • For GitHub.com integrations:

    If you host LGTM on a server that is accessible to untrusted users, you should restrict access by defining a Login allowlist. Otherwise adding integration with this public service will enable any of its users to log in to your system.

Defining the integration

Using separate browser windows, log in to LGTM Enterprise, and either GitHub.com or GitHub Enterprise (depending on which you are integrating with). This will make it easier to copy and paste data between the two applications.

1. In LGTM Enterprise, start defining the integration

  1. In LGTM's administration interface, go to the Integrations page.

  2. Click Add new integration to display the Integrate with a new system page.

  3. In the drop-down list, select either GitHub Enterprise (Apps) or GitHub.com (Apps).

  4. Click Continue to display the detailed definition page.

  5. For GitHub Enterprise: enter the root URL for the GitHub Enterprise instance in the URL field.

  6. Copy the value in the Callback URL field. You will use this in GitHub.

2. In GitHub.com or GitHub Enterprise, create a GitHub App

  1. In the upper-right corner of any page, click your profile photo, then click Settings.

  2. In the left sidebar, under "Organization settings," click the organization you want to use to register LGTM Enterprise as a GitHub App.

    Although you can use a personal GitHub account to register LGTM Enterprise as a GitHub App, there are benefits to using an organization. For details, see Configuring access requests to come from "LGTM" below.

  3. On the Organization profile page, in the left sidebar, under Developer settings, click GitHub Apps.

  4. Click New GitHub App.

  5. Enter a GitHub app name.

    Give your app a clear and succinct name. We recommend: LGTM. Your app cannot have the same name as an existing GitHub user, unless it's your own user or organization name.

  6. Optionally, enter a description of your app that users will see.

  7. In Homepage URL, enter the full URL of the home page of your LGTM Enterprise instance.

  8. In User authorization callback URL, paste the URL you copied from LGTM.

  9. Leave Request user authorization (OAuth) during installation unselected.

  10. Leave Setup URL empty.

  11. Leave Redirect on update unselected.

  12. Leave Active selected.

  13. Go back to the separate browser window for LGTM, copy the Webhook URL, and paste it into the Webhook URL field in the GitHub form.

  14. In Webhook secret, enter some text of your choice. Make a note of this value because you must enter the same value in LGTM. This text acts as a secret token that secures your webhooks.

  15. Leave Enable SSL verification selected.

  16. Alter the permissions as follows, leaving everything else as "no access."

    Repository permissions

    • Checks: read & write
    • Contents: read-only
    • Metadata: read-only
    • Pull requests: read & write

    User permissions

    • Email addressses: read-only
  17. Under "Subscribe to events," select Pull request and leave all other events unselected.

  18. Choose where the app can be installed by selecting either Only on this account or Any account. For more information on installation options, see the GitHub help topic "Making a GitHub App public or private."

  19. Click Create GitHub App.

    You'll now copy values from the page that's displayed back into LGTM Enterprise.

  20. Copy the Client ID.

3. Finish defining the integration

  1. Back in LGTM Enterprise, paste the value you copied from GitHub into the Client ID field, replacing any value your browser may have autofilled into this field.

  2. Copy the Client secret value from GitHub to LGTM, replacing any value your browser may have autofilled into this field.

  3. In the Login allowlist field, in LGTM, specify the email domains (or email addresses) that you want to support. This limits which GitHub user accounts can be used to authenticate with LGTM Enterprise. While this field is optional, it's recommended that you use it unless you have set up a global allowlist, or are confident that only trusted users have access to the server that LGTM runs on.

  4. You can edit the Short name in LGTM, but this isn't usually necessary. This is used in the URLs for LGTM projects associated with this integration. For example, 'g' in https://lgtm.com/projects/g/jquery/jquery/. The short name can't be edited once you've added a project using this integration.

  5. Copy the App ID from GitHub to LGTM.

  6. In GitHub, still on the General settings page for your GitHub App, copy the final part of the URL for the page from the browser's address bar.

    This string is derived from the App name of your GitHub App. For example, if you called the GitHub App "LGTM" the string to copy is "lgtm."

    Paste this into the App name field in LGTM.

  7. In LGTM, enter the same Webhook secret that you entered into GitHub previously.

  8. Generate a private key:

    1. In GitHub, scroll to the bottom of the General settings page for your GitHub App and click Generate private key.

    2. Download the file that is generated.

    3. Open the file in a text editor.

    4. Copy the complete file contents.

    5. Paste this text into the Private key field in LGTM.

  9. Generate the default installation ID:

    The default installation ID provides an alternative way of allowing GitHub to authenticate communication from LGTM Enterprise. An example of when LGTM uses this ID is when the application needs to make authenticated requests to the GitHub API that are not in the context of a particular repository.

    1. In GitHub, click Install App in the left sidebar.

    2. Click Install for the organization you want to use.

    3. On the confirmation page, click Install again.

    4. The settings page for the newly installed GitHub App is displayed. It has a URL like this, with a number at the end:

      https://github.com/organizations/<organization>/settings/installations/<installation-ID>

      Copy the installation ID number at the end of the URL.

    5. Paste the installation ID into LGTM.

  10. Set Authorization mechanism and Allow adding projects through the frontend as required.

  11. Click Add to save the new integration.

  12. When the Integrations page is redisplayed, click the Test button associated with the new integration to verify that everything is set up correctly.

You can now add projects using the Add tab of the Projects page.

Configuring access requests to come from "LGTM"

When a user browses to LGTM Enterprise and clicks the button to log in with their GitHub Enterprise login, they are taken to GitHub Enterprise's sign-in page (unless they are already currently signed into GitHub Enterprise). Then—on their first log in to LGTM only—a message is displayed requesting them to grant access to their GitHub account for <GitHub App name> by <organization or user who registered the app>.

To avoid this request for access coming from your own personal GitHub Enterprise account, use a GitHub Enterprise organization to register LGTM Enterprise as a GitHub App.

For more information about GitHub organizations, see the GitHub help.

Related topicsRelated topics