# How to Connect Teamscale to GitHub

Teamscale integrates with GitHub as a GitHub App. This applies to both the official github.com platform and custom installations of GitHub Enterprise.

Minimum Enterprise Version

The minimum required GitHub Enterprise version for the integration to work is 2.14.

# Prerequisites for GitHub integration

Prerequisites for the configuration are:

  • Teamscale license with GitHub support enabled.
  • Teamscale installation that can be reached from the GitHub instance you want to connect to.
  • GitHub organization used to register the GitHub App.
  1. Ensure that the public base URL is configured correctly in Teamscale. For this, open the settings page (Admin > Settings) and check the entry Teamscale instance base URL in tab Server Settings. This should point to the URL of the server that is reachable by the GitHub installation.

  2. In GitHub, navigate to the settings page of your organization. Open Developer Settings > GitHub Apps and click the button New GitHub App. Here you can provide a name and details of your app. The following fields are relevant for Teamscale:

    • User authorization callback URL: This is the public URL of your Teamscale installation followed by api/github/oauth. So for the Teamscale URL https://teamscale.acme.com, this would be https://teamscale.acme.com/api/github/oauth.
    • Setup URL: Should be left empty.
    • Webhook URL: This is the public URL of your Teamscale installation followed by api/github/web-hook. So for the Teamscale URL https://teamscale.acme.com, this would be https://teamscale.acme.com/api/github/web-hook.
    • Webhook secret: While this is optional, it is a good idea to place a random string in here. Remember this string for later usage in Teamscale.
    • Repository permissions:
      • Checks: Read & write
      • Contents: Read-only
      • Issues: Read-only
      • Metadata: Read-only (the default)
      • Pull requests: Read & write
      • Commit statuses: Read & write
    • Organization permissions:
      • Members: Read-only
    • Subscribe to events:
      • Issues
      • Pull request
      • Push
  3. Still in GitHub, you now have to generate a private key for your application. This can be done in the section Private keys in the general settings of your GitHub App. Download and save the key for later.

  4. Back in Teamscale, go to GitHub Integration on the settings page and fill the fields as follows:

    • GitHub URL: Enter the URL of your GitHub installation. For the public GitHub instance use https://github.com/.
    • ID of the GitHub app: This value can be found at the top of the settings page of your GitHub App (App ID).
    • Application private key: Enter the private key you just downloaded in step 3.
    • Secret used for securing webhook calls: This is the webhook secret you configured in step 2. If you did not use a webhook secret, leave this empty.
    • OAuth client id: This value can be found at the top of the settings page of your GitHub App (Client ID).
    • OAuth client secret: This value can be found at the top of the settings page of your GitHub App (Client secret).
    • Use GitHub for Single Sign On: Check this box if you want to allow users to log into Teamscale using their GitHub account.
    • Create a new user on first login: Check this box if you want users that log into Teamscale using GitHub but do not have a Teamscale account yet to be created automatically.
  5. Go back to the settings page of your GitHub App and switch to the Advanced tab. Check the Recent Deliveries. There should be a successful ping attempt in the list.

To install this GitHub App for your repository, navigate to the settings page of the GitHub App and select Install App. This allows Teamscale to access you repositories and vote pull requests. Note that Teamscale projects are not automatically created, but rather have to be created as needed using the GitHub connector.

Teamscale ensures that only users that have access to a repository on GitHub can create or modify a GitHub connector for that repository in Teamscale. This ensures that only authorized users can import code from a repository into Teamscale.

To that end, whenever you modify or create a GitHub connector in Teamscale, Teamscale checks your Teamscale user name against the list of team members and collaborators who have read access to the corresponding repository on GitHub. If your Teamscale user name is not in that list, you will not be able to create/modify the Teamscale project.