Setting up a GitHub App

You need to use a GitHub App to connect SonarQube with a GitHub instance in order to be able to use the integration features.

You need to use a GitHub App to connect SonarQube with a GitHub instance in order to be able to use the following features:

• Importing your GitHub repositories into SonarQube.

• Delegating the SonarQube user authentication to GitHub.

You need the global Administer System permission in SonarQube to perform this setup.

Setup overview

The SonarQube Server uses the GitHub App to access GitHub resources as illustrated below. The GitHub resources access permissions are set in the App. A "GitHub Configuration" record is used in SonarQube to access the GitHub App. A different Configuration is used to manage the repository import and the user authentication.

Starting in Enterprise Edition, you can set up the integration of SonarQube with multiple GitHub instances, each instance being accessed with a different GitHub App.

To set up a GitHub App to integrate SonarQube with GitHub:

1. Register a GitHub App for SonarQube.

2. Install the App on the organization(s) SonarQube needs to access.

3. Add the App to SonarQube’s global setup through a "GitHub Configuration" record. You must:

   • Create one GitHub Configuration for the GitHub repository import.

   • Create one GitHub Configuration for the user authentication delegation.

Step 1: Register SonarQube as a GitHub App

See GitHub’s documentation on registering a GitHub App for general information on GitHub Apps.

In the procedure below, we recommend registering a public App. You can register a private App if you have only one GitHub organization. In that case, you must register the App under that organization.

Specify the following settings in your app:

• GitHub App Name: Your app’s name. Example: sonarqube.

• Homepage URL: Your SonarQube instance’s base URL (for information purposes only).

• Callback URL: Your SonarQube instance’s base URL (the URL used to redirect to the SonarQube server).

• Webhook URL: To improve security, webhooks, by default, are not allowed to point to the SonarQube server. Therefore, we recommend that you disable the feature unless you want to enable code scanning alerts for security issues in GitHub. To disable the feature, clear the Webhook Active checkbox to silence a forthcoming deprecation warning, and clear the Webhook URL and Webhook secret fields.

• Under Permissions & events, set up the permissions and events as explained below. Some permissions or events are only necessary depending on the purpose of the integration.

Permissions & events

Repository permissions

Permission	Access	Note
Checks	Read & Write
Administration	Read-only	Required only for user provisioning.
GitHub Enterprise: Repository metadata GitHub.com: Metadata	Read-only
Pull Requests	Read & Write
Private repositories: Content	Read-only
Code scanning alerts	Read & Write	Required only if you want to report security alerts raised in SonarQube to GitHub. When you update this permission, GitHub sends an email to the GitHub organization’s administrator, asking them to validate the changes on the installation of the GitHub App.

Organization permissions

Permission	Access	Note
Administration	Read-only	Required only for user provisioning.
Members	Read-only
Projects	Read-only

Account permissions

Permission	Access	Note
Email addresses	Read-only	Required only for user authentication and provisioning.

Subscribe to events

Only if you want to report security alerts raised in SonarQube to GitHub:

Select Code scanning alert.

• Under Where can this GitHub App be installed? select Any account to make the App public in order to allow you in step 2 to install the App on any organization**.**

Step 2: Install the SonarQube GitHub App on your organization(s)

You need to install the SonarQube GitHub App on the GitHub organizations that SonarQube will need to access. See GitHub’s documentation on installing GitHub Apps for more information.

Step 3: Add the GitHub App to SonarQube’s global setup

You need to create a GitHub Configuration record in SonarQube and add the SonarQube GitHub App to it. The setup is different depending on your integration purpose:

If you want to support the GitHub repository import

To add the GitHub App to SonarQube’s global setup for repository import:

1. In the SonarQube UI, go to Administration > Configuration > General Settings > DevOps Platform Integrations.

2. Select the GitHub tab and click Create configuration. The New GitHub configuration dialog opens.

3. Specify the settings: see Configuration settings below.

If you want to delegate the user authentication to GitHub

To add the GitHub App to SonarQube’s global setup for user delegation, go to Administration > Configuration > General Settings > Authentication > GitHub. See Connecting your GitHub App to SonarQube in GitHub.

Configuration settings

Field	Description	Note
Configuration name	The name used to identify your GitHub Configuration. Use something succinct and easily recognizable.	Only available in editions authorizing the integration with multiple GitHub instances: Enterprise Edition and Data Center Edition.
GitHub API URL	The API URL of the GitHub instance. For example, https://github.company.com/api/v3 for GitHub Enterprise or https://api.github.com/ for GitHub.com.
GitHub App ID	The App ID of your GitHub App (on GitHub, go to Settings > Developer Settings > GitHub Apps to view your App).
Client ID	The Client ID of your GitHub App’s page.
Client Secret	The Client secret of your GitHub App’s page. Administrators can encrypt this secret at Administration > Configuration > Encryption. See Settings Encryption in Security for more information.
Private Key	Your GitHub App’s private key in PEM format. You can generate a .pem file from your GitHub App’s page under Private keys. Copy and paste the whole contents of the file here.	Administrators can encrypt this key at Administration > Configuration > Encryption. See Settings Encryption in Security for more information.
Webhook Secret	Webhook secret defined in your GitHub App to enable the report of code scanning alerts..	Required only if you want to enable code scanning alerts for security issues in GitHub.