How to Connect Teamscale's Code Connector to GitHub via GitHub App

Teamscale integrates with GitHub as a GitHub App. This applies to both the official github.com platform and custom installations of GitHub Enterprise. The guide for connecting to the issues on GitHub via App can be found here or via an Access Token can be found here.

General Option Reference

This guide only covers the options specific for the GitHub repository connector. A general overview of connector options is available here.

Minimum Enterprise Version

If you use GitHub Enterprise, version 2.14 or later is required.

Prerequisites for GitHub integration

Prerequisites for the configuration are:

• Teamscale installation that can be reached from the GitHub instance you want to connect to.
• GitHub organization used to register the GitHub App.

Installation of the Teamscale GitHub App

1. Ensure that the Teamscale instance base URL is configured correctly.

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
   • Account permissions:
     • E-mail addresses: Read-only
   • Subscribe to events:
     • Check run
     • Issues
     • Pull request
     • Push
     • Status

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. In Github, 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 username against the list of team members and collaborators who have read access to the corresponding repository on GitHub. If your Teamscale username is not in that list, you will not be able to create/modify the Teamscale project.

TIP

If you are not using Login with Github, you probably want to disable the Skip check if the current user is a collaborator during project creation setting in Teamscale's Github Application setting (Admin Perspective > Settings > Github Integration > Your App). Otherwise you will not be able to create a new project using the Github Application, unless you mirror the exact usernames used in Github in Teamscale..

TIP

If there are restrictions, so that Teamscale cannot receive GitHub web hooks or web hooks cannot be automatically created, please apply these advanced configuration options.