GitHub Applications

Teamscale supports integration with GitHub through GitHub Apps which enables both signing in via GitHub accounts and Teamscale's pull request integrations. GitHub Apps can be configured for both github.com and GitHub Enterprise Server instances.

To add an App, go to Admin > Settings > GitHub Integration and click on + Add under GitHub Application. A dialog asking for a GitHub Application ID will open. This ID is only used as a unique identifier within Teamscale and does not have to match anything in GitHub. After clicking on Ok, a new App will be created and the following configuration options will be available.

How to Set Up a GitHub Application

For more detailed instructions on setting up a GitHub Application, see our how-to guide.

Configuration Options

GitHub URL	The URL of the GitHub instance to connect to. For github.com, use https://github.com/ (default). For GitHub Enterprise Server, provide your server's URL, e.g. https://github.enterprise.company.com/. Supported protocols are HTTP and HTTPS. The URL must be a root URL, i.e., it must not contain a path.
ID of the GitHub App	The unique numerical identifier assigned to your GitHub App. This can be found in the App's settings in GitHub under App ID.
App Name (as used in the URL)	The URL-friendly name of your GitHub App. Copy this from the URL of the App's settings page on GitHub.
Application private key (PEM)	The private key for your GitHub App in PEM format. The key can be generated on the App's settings page on GitHub.
Secret used for securing webhook calls (optional)	The webhook secret is used to verify that webhook calls are actually from GitHub. While optional, it's highly recommended for security. The secret can be added on the App's settings page on GitHub. You can use an arbitrary string, but we recommend following common password guidelines. For more information, please refer to the GitHub documentation.
OAuth client id	The OAuth client ID for your GitHub App. This is used for user authentication and authorization flows. You can find the client id on the App's settings page on GitHub.
OAuth client secret	The OAuth client secret for your GitHub App. This works together with the client ID for user authentication. The secret can be generated on the App's settings page on GitHub.
Skip check if the current user is a collaborator during project creation	When enabled, Teamscale will not verify if the current user has collaborator access to the repository when creating projects.
Use GitHub for Single sign-on (SSO)	Enable GitHub-based single sign-on authentication. When enabled, users can log into Teamscale using their GitHub accounts.
Display name for the login button	The text displayed on the login button when SSO is enabled. This should be descriptive of your GitHub instance (e.g., "Login with GitHub" or "Login with MyOrganization's GitHub").
Create a new user on first login	When enabled, new users will be automatically created in Teamscale when they first log in via GitHub SSO.
Allowed Organizations for SSO	Comma-separated list of GitHub organization names (as in the URL) whose members are allowed to log in with SSO. If this option is not set, logins will not be possible. Important: This is a critical security setting. Setting Default groups for imported users without specifying Allowed Organizations for SSO can create a security vulnerability. If your GitHub App is available to other organizations, a user from an unauthorized organization could install the App on their organization and gain access to your Teamscale instance via SSO. They would be assigned to the default groups, potentially giving them access to projects on Teamscale which they would usually not have access to on GitHub. Therefore, the option is always required as a precautionary security measure.
Default groups for imported users	Comma-separated list of Teamscale user group names that will be assigned to users who log in via GitHub SSO. These groups must exist in Teamscale before users attempt to log in.