# Setting up a GitHub App You need to use a GitHub App to connect SonarQube Server with a GitHub instance in order to be able to use the following features: * Importing your GitHub repositories into SonarQube Server. * Delegating the SonarQube Server user authentication to GitHub. You need the global Administer System permission in SonarQube Server to perform this setup. ## Setup overview To set up a GitHub App to integrate SonarQube Server with GitHub: 1. Before starting, see [#related-pages](https://docs.sonarsource.com/sonarqube-server/devops-platform-integration/introduction#related-pages "mention"). 2. Register a GitHub App for SonarQube Server. 3. Install the App on the organizations SonarQube Server needs to access. 4. Add the App to SonarQube Server’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 a GitHub App for SonarQube Server See GitHub’s documentation on [registering a GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/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: 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 [report-security-alerts](https://docs.sonarsource.com/sonarqube-server/devops-platform-integration/github-integration/setting-up-at-global-level/report-security-alerts "mention") 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 & 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 | | ------------------------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](https://docs.sonarsource.com/sonarqube-server/instance-administration/ai-features/autodetect-ai-code "mention") 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 in step 2 to install the App on any organization. ## Step 2: Install the GitHub App for SonarQube Server in your organizations You need to install the GitHub App for SonarQube Server on the GitHub organizations that SonarQube Server will need to access. See GitHub’s documentation on [installing GitHub Apps](https://docs.github.com/en/free-pro-team@latest/developers/apps/installing-github-apps) for more information. ## Step 3: Add the GitHub App to SonarQube Server’s global setup You need to create a GitHub Configuration record in SonarQube Server and add the 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 Server’s global setup for repository import: 1. In the SonarQube, 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 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](https://docs.sonarsource.com/sonarqube-server/instance-administration/authentication/github "mention") 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, for GitHub Enterprise or 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 [encrypting-settings](https://docs.sonarsource.com/sonarqube-server/instance-administration/security/encrypting-settings "mention"). |


| | 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 [encrypting-settings](https://docs.sonarsource.com/sonarqube-server/instance-administration/security/encrypting-settings "mention"). | | 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. |
{% hint style="info" %} Standard GitHub procedures require confirmation when access levels are changed. Typically, this is done by confirming via an email sent to administrators. {% endhint %} ## Related online learning * :desktop: [Configure a GitHub App for SonarQube Server](https://www.sonarsource.com/learn/course/sonarqube-server/58844141-6a47-4fba-b219-d88d7054a045/configure-a-github-app-for-sonarqube-server)