Setting up a GitHub App

Setting up a GitHub App for use with SonarQube Server.

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

• Importing your GitHub repositories into SonarQube Server.
• Delegating the SonarQube Server user authentication to GitHub.
• Reporting the quality gate status and analysis summary in your GitHub pull requests.
• Blocking pull request merges with GitHub branch protection rules when the quality gate fails.

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

Setup overview

The setup consists of three stages:

1. Create or register a GitHub App — two methods are available:

   • Create configuration: You register and configure the app on GitHub yourself, then enter the credentials in SonarQube Server. Use this path if your network configuration prevents the automatic flow, if your integration requires code scanning alert permissions, or if you already have a GitHub App you want to reuse.
   • Create app for me (recommended): SonarQube generates a preconfigured app and redirects you to GitHub to authorize its creation. SonarQube saves the resulting credentials automatically. Organization Owners complete the installation directly. Organization Members can initiate the flow, but an Owner must approve the installation to complete it.
2. Install the app on the GitHub organizations that SonarQube Server needs to access.
3. Add the app to SonarQube Server's global setup.

Create a GitHub App automatically

When you choose Create app for me, SonarQube creates the GitHub App with the required settings and permissions, and saves the credentials in SonarQube Server automatically.

Prerequisite

You need a GitHub account with an organization Owner or Member role. If you are an organization Owner, you can create and install the app in one step. If you are an organization Member, GitHub sends an installation approval request to your organization Owners. The app is active in SonarQube Server once an Owner approves it.

To create a GitHub App automatically:

1. In the SonarQube UI, go to Administration > Configuration > General Settings > DevOps Platform Integrations.
2. Open the GitHub tab and select Create app for me. Your window will open in GitHub to continue.
3. In GitHub, enter your GitHub organization and a unique Configuration name.

   • Optionally, select Also set up GitHub authentication to enable users to sign in using their GitHub login credentials.
4. Select Continue to GitHub to confirm access, after which the Create GitHub App page will open.
5. Add your GitHub App name and select Create GitHub App for Your GitHub Organization to continue. You can always change the app name later.
6. A new page will open where you must select the GitHub organization where you want to install the app.
7. Select either All repositories or Only select repositories to bind to SonarQube Server.
8. To complete the installation, select Install & Authorize to finish. GitHub will redirect you back to SonarQube Server. The App ID, Client ID, Client Secret, and Private Key are saved automatically in a new GitHub Configuration record.

SonarQube pre-configures the app with the following permissions, which are shown on GitHub for review:

• Read access to administration, code, members, metadata, organization administration, and organization projects.
• Read and write access to checks and pull requests.
• Read access to email addresses (user permission).

If your integration requires code scanning alert permissions (to report security alerts to GitHub), use the manual setup instead. See Create a GitHub App manually.

After the app is created, install it on your GitHub organizations.

If the automatic flow fails

If the automatic flow fails (for example, because of network or firewall restrictions between SonarQube Server and GitHub), use the manual setup instead. See Create a GitHub App manually.

Create a GitHub App manually

Use manual setup if:

• Your SonarQube Server cannot complete the automatic flow (for example, because of network or firewall restrictions).
• Your integration requires code scanning alert permissions to report security alerts to GitHub.
• You already have a GitHub App for SonarQube Server and want to reuse it.

If you already have a GitHub App, skip the registration steps below and go directly to Add the GitHub App to SonarQube Server's global setup.

After registering a new app, continue with Install the GitHub App in your organizations.

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

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: sonarqubeserver.
• Homepage URL: Your SonarQube Server instance's base URL (for information purposes only).
• Callback URL: Your SonarQube Server 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 alerts for security issues in GitHub. See Setting up the report of security alerts for more information. 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 and Subscribe to events, set up the permissions and events as explained below in the list of settings. Some permissions or events are only necessary depending on the purpose of the integration.

Permissions and Subscribe to events settings

Repository permissions

Permission	Access	Note
Administration	Read-only	Required only for user provisioning.
Checks	Read & Write
Code scanning alerts	Read & Write	Required only if you want to report security alerts raised in SonarQube Server 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.
Contents	Read-only
In GitHub Enterprise Server: Repository metadata In GitHub.com: Metadata	Read-only
Pull Requests	Read & Write

Organization permissions

Permission	Access	Note
Administration	Read-only	Required only for user provisioning.
GitHub Copilot Business	Read-only	Required only to use SonarQube Server's Autodetect AI-Generated Code feature. (Autodetect AI code is deprecated)
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 Server 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 to install the App on any organization.

After registering the app, install it on your GitHub organizations.

Install the GitHub App in your organizations

Install the GitHub App on each GitHub organization that SonarQube Server needs to access. See GitHub's documentation on installing GitHub Apps for more information.

Add the GitHub App to SonarQube Server's global setup

If you chose Create app for me, SonarQube has already created a GitHub Configuration record for repository import. You only need to complete this step if you used the manual setup, or if you want to set up user authentication delegation.

If you want to support the GitHub repository import

To add the GitHub App to SonarQube Server’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 select Create configuration. The Create a configuration dialog opens.
3. Specify the settings in the Configuration settings section below.

If you want to delegate the user authentication to GitHub

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

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. See Sensitive settings.
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. See Sensitive settings.
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.

Note: Standard GitHub procedures require confirmation when access levels are changed. Typically, this is done by confirming via an email sent to administrators.

Related online learning

• Configure a GitHub App for SonarQube Server