This document outlines the configuration, permission requirements and app configuration to get started with your Github account and DeepSource Enterprise.

​
Quick Setup

To create the app, you can run this quick setup script with a few additional steps. This script will open up a website with the Github app creation page and fill in the required fields automatically.

python3 <(curl -s https://raw.githubusercontent.com/DeepSourceCorp/enterprise-assets/master/integrations/create_github_app.py)

If you get a 404 page when the quick setup script is run, ensure that you’re logged in and that you have the permission to create apps — Admin access — for the respective organization.

  1. When you run the command in the CLI, a few user details will have to be filled in:

    1. The URL of your self-hosted Github instance: For Github Cloud, you can skip this step and leave it blank. This will automatically use the default https://github.com domain.
    2. An organization slug: If your organization is at https://github.com/my-organization, enter my-organization here.
    3. The URL of your DeepSource installation: This should be the URL you have configured as the Application Hostname on the Admin Console.
      • For a self-hosted Github Enterprise Server installation, this hostname/IP must be reachable by your Github Enterprise Server installation.
      • If you are using Github cloud, the URL must be reachable from the IP public internet.

  2. The script will open a new browser page. Complete the following steps:

    1. Scroll to the “Webhook” section and check “Active”.
    2. Supply a random string as the Webhook Secret. Make sure to remember it, as you will need it later.
    3. Scroll to the User Permissions section and select Read-only for Email addresses and Git SSH Key.

  3. Click on Create GitHub App.

  4. This will take you to the About page for your Github application. Scroll down the page to the Private keys section and press Generate a private key. Keep this key safely since you will need to upload this in the Admin Console in the next section.

  5. Note down the following values:

    1. Your app slug: This can be found in the URL. Copy the value for the APP_SLUG part of the URL on the Github app page. https://github.com/organizations/acme_corp/settings/apps/<APP_SLUG>
    2. Application ID
    3. Client ID
    4. Client Secret: You can generate this by clicking on the Generate a new client secret button.

  6. You will use these values to configure the Github App in the Admin Console. Follow the next steps to continue.

  7. Click on Save config and deploy. (Ensure that you have completed the steps in the Adming Console page before you deploy.)

  8. Visit the login page on https://<DEEPSOURCE_HOSTNAME>/loginto start using Github with DeepSource Enterprise.

​
Configuring the Github app in the Admin Console

After you create your Github application, you need to configure these in the Admin Console for the application to use it.

  1. Visit the Admin Console

  2. Navigate to Application -> Config.

  3. Select the checkbox Github

  4. Fill up the values from the previous step for:

    1. Github Application ID
    2. Github Application Slug
    3. Github App Client ID
    4. Github App Client Secret Key
    5. GitHub Application Webhook Secret
    6. Github Application Private Key

  5. Save

PermissionScopeReason
ChecksRead and writeUpdate pull request checks when an analysis is run.
Commit statusesRead and writeFor updaing commit statuses in the PR.
ContentsRead and writeGet source code during analysis.
MetadataRead-onlyThe metadata permission provides access to a collection of read-only endpoints with metadata for various resources.
Pull requestsRead and writeCreate pull requests for autofix.
Single fileRead and writeRead and write the .deepsource.toml
WebhooksRead-onlyReceive webhook notifications when the source code changes.
Email addressRead-onlyTo authenticate your user account.
Git SSH KeyRead-onlyFor cloning private repositories.