Setting up the GitHub integration with SonarQube at the global level

This section explains how to set up GitHub and SonarQube for their integration at the global level. You need the global Administer System permission in SonarQube to perform this setup.

Setting up a GitHub App to integrate SonarQube with GitHub

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.

Setup overview

You will register a GitHub App for SonarQube, install it on the organization(s) SonarQube needs to access, and then add it to SonarQube's global setup through a "GitHub configuration" record.

In the Community Edition, you can only manage one GitHub configuration in SonarQube. Starting in the Developer Edition, you can set up access to multiple GitHub instances:

• As part of Developer Edition, you can access several GitHub instances, each instance being accessed through a GitHub App. To do so, register a GitHub App for each GitHub instance and create in SonarQube a GitHub configuration for each registered App.
• Starting in Enterprise Edition, you can access several GitHub instances and you can access each instance using different GitHub Apps. 

Step 1: Register SonarQube as a GitHub App

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

Specify the following settings in your app:

• GitHub App Name: Your app's name. Example: sonarqube.
• Homepage URL: The public URL of your SonarQube server.  Example: https://www.sonarqube.org/.
• Callback URL: Your SonarQube instance's base URL. For example, http://sonarqube.yourcompany.com. Note that for this to work, your SonarQube instance must be accessible through a public URL.
• 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.

• 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. 

To add the GitHub App to SonarQube's global setup:

1. In the SonarQube UI, go to Administration > Configuration > General Settings > DevOps Platform Integrations. 
2. Select the GitHub tab and click Create configuration. The Create a configuration dialog opens. 
3. Specify the following settings:
   • Configuration Name (Enterprise Edition and Data Center Edition only): The name used to identify your GitHub configuration at the project level. Use something succinct and easily recognizable.
   • GitHub  API URL: 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 is found on your GitHub App's page on GitHub at Settings > Developer Settings > GitHub Apps.
   • Client ID: The Client ID is found on your GitHub App's page.
   • Client secret: The Client secret is found on your GitHub App's page. Administrators can encrypt this secret at Administration > Configuration > Encryption. See Settings Encryption 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 for more information.
   • Organizations: Specify the allowed GitHub organizations.
     This setting is highly important if you want to delegate the SonarQube user authentication to GitHub. Not specifying the allowed organizations will represent a security breach:
     • For automatic provisioning, not entering the allowed organizations for a public App can let undesired users authenticate to your SonarQube instance, as public GitHub Apps can be installed by anyone.
     • When using Just-in-Time provisioning, if the allowed organizations are not entered, any user with a GitHub account can log in to the SonarQube instance, even if the GitHub App used for authentication is private.
4. Select the Save configuration button. 

Setting up the connection to SonarQube for GitHub Actions workflows

To securely store the connection parameters to the SonarQube Server, use GitHub secrets: see GitHub's documentation on Encrypted secrets for more information. This setting will apply to all GitHub Actions workflows.

Proceed as follows:

1. In the SonarQube UI, generate a SonarQube token at the global level for GitHub.
2. To store the authentication token in GitHub, create a new repository secret in GitHub with :
   • Name: SONAR_TOKEN
   • Value: the token you generated in the previous step.
3. To store the SonarQube Server URL in GitHub, create a new repository secret in GitHub with:
   • Name: SONAR_HOST_URL
   • Value:  SonarQube Server URL. 

Setting up SonarQube user provisioning and authentication through GitHub

See Authenticating with GitHub.

Setting up the report of security alerts in GitHub

Understanding the feature setup

SonarQube can report the security issues to GitHub's Code scanning alerts by accessing GitHub through the GitHub App you have configured in Setting up a GitHub App to integrate SonarQube with GitHub. In this App, the feature must be enabled.

The update of a security alert status change in SonarQube is performed through a webhook mechanism as illustrated below. The procedure is as follows:

1. When a user changes a security alert status in GitHub, a webhook event is generated.
2. GitHub sends a webhook request to SonarQube to inform it about the event. To do so, it retrieves the webhook URL and the webhook secret from the SonarQube GitHub App.
3. SonarQube checks the received webhook secret against the secret stored in the respective SonarQube project's GitHub configuration.
4. If the check is successful, SonarQube updates the status in the respective security issue.

To allow users to set up the feature for their project, you must provide them with the webhook secret that they will add to the GitHub configuration of their SonarQube project.

Enabling the feature in the SonarQube GitHub App

If not already done, edit your SonarQube GitHub App to enable and set up the report of security alerts to GitHub:

1. In GitHub, go to Settings > Developer settings > GitHub Apps and select your GitHub App.
2. Go to the General > Webhook section and make sure to select the active checkbox.
3. Add the following Webhook URL:  https://<yourinstance>.sonarqube.com/api/alm_integrations/webhook_github. Replace <yourinstance>.sonarqube.com with your SonarQube instance.
4. Set a Webhook secret (see GitHub's webhook security recommendations).
5. Under Permissions & events > Repository permissions > Code scanning alerts, set the access level to Read and write. 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.
6. Under Permissions & events > Subscribe to events, select Code scanning alert.

Verifying that the SonarQube server URL is correctly set

If the URL of your SonarQube server is not configured then integration features may not work correctly.

To verify the server URL:

• Go to Administration > Configuration > General Settings > General > General and check the instance's Server base URL.