# GitHub

To allow users to log in with GitHub credentials, you must use a GitHub App. We recommend that you set up a dedicated GitHub app for your SonarQube integration.

## Creating a dedicated app for authentication <a href="#creating-a-dedicated-app-for-authentication" id="creating-a-dedicated-app-for-authentication"></a>

First, you’ll need to [create a GitHub App](https://docs.github.com/en/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app). If you’re already using a GitHub App for pull request decoration (see [github-integration](https://docs.sonarsource.com/sonarqube-server/10.1/devops-platform-integration/github-integration "mention")), you can also use it for user authentication and provisioning.

Configure the following settings in your GitHub App:

* **General** tab:
  * **Homepage URL**: The public URL of your SonarQube server. For example, `https://sonarqube.mycompany.com`. For security reasons, HTTP is not supported, and you must use HTTPS. The public URL is configured in SonarQube at **Administration > General > Server base URL**.
  * **Callback URL**: The public URL of your SonarQube server. For example, `https://sonarqube.mycompany.com`.
  * **Webhooks**: Deactivate the feature.
* **Permissions & events** tab:
  * **Organization Permissions > Members**: Set to **Read-only**.
  * **Account permissions > Email addresses**: Set to **Read-only**.
* **Install App** tab: Click **Install** and validate the installation on each organization you need.
* During App creation, or under the **Advanced** tab, you can make the App *private* or *public*:
  * Make it *private* if you only have one organization.
  * Make it *public* if you have several organizations from where you need users to authenticate and/or be provisioned. Don’t forget to list those as allowed organizations in SonarQube (see below).

## Setting your authentication settings in SonarQube <a href="#setting-your-authentication-settings-in-sonarqube" id="setting-your-authentication-settings-in-sonarqube"></a>

### Connecting your GitHub App to SonarQube <a href="#connecting-your-github-app-to-sonarqube" id="connecting-your-github-app-to-sonarqube"></a>

**Step 1**: In SonarQube, Navigate to **Administration** > **Configuration** > **General Settings** > **Authentication** > **GitHub** and click **Create configuration**.

**Step 2:** Fill the following fields with information from your GitHub App:

* * **Client ID**
  * **Client Secret**
  * **GitHub App ID**
  * **Private Key**

**Step 3:** Fill the **API url** and **WEB url** fields as recommended by GitHub.\
\*\*\
Step 4:\*\* If your GitHub App is public, it is important that you enter the allowed organizations in the **Organizations** field.

{% hint style="warning" %}
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.
{% endhint %}

**Step 5:** Click **Save** **configuration**.

### Selecting the user and group provisioning method <a href="#selecting-the-user-and-group-provisioning-method" id="selecting-the-user-and-group-provisioning-method"></a>

Once you’ve created your GitHub configuration, you can choose how users and groups are provisioned to SonarQube. For an overview of the available provisioning methods, see [overview](https://docs.sonarsource.com/sonarqube-server/10.1/instance-administration/authentication/overview "mention").

**Step 1:** From the **Authentication > GitHub** tab, click **Enable configuration**.

**Step 2:** Select a **provisioning method**. The available options are:

* * **Just-in-Time user and group provisioning (default)**:
    * Users are provisioned when they authenticate through GitHub for the first time if the option **Allow users to sign up** is enabled.
    * User information and group memberships are updated at each authentication.
    * (Optional) You can synchronize GitHub teams with existing SonarQube groups of the same name with the **Synchronize teams as groups** option.
  * **Automatic user and group provisioning**
    * Users and groups will be synchronized on an hourly basis. The first synchronization happens immediately when you enable the feature.
    * You can check the status of the synchronization on this configuration page, in the box **Automatic user and group provisioning** box.
    * If needed, you can manually trigger a synchronization by clicking **Synchronize now**.
    * Groups in SonarQube are named after the GitHub organizations and teams’ names, ie. *Organization/Team.*
    * Personal user information (name and email address) is updated only upon user authentication.

**Step 3:** When you change a setting in your configuration, you can force SonarQube to check that it is valid by clicking **Test configuration.**

**Step 4:** Click **Save**.

From the login page, your users can now connect to SonarQube using their GitHub accounts by clicking the **Login with GitHub** button.