> For the complete documentation index, see [llms.txt](https://docs.sonarsource.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sonarsource.com/sonarqube-server/2025.1/instance-administration/authentication/github.md).

# GitHub

To let users sign in with GitHub credentials, register SonarQube Server as a GitHub App. This also lets you configure user, group, and permission provisioning.

{% hint style="warning" %}
Compatibility with OAuth apps is deprecated and will be removed in the future. The use of GitHub Apps is required for automatic provisioning of users and groups. If you’re still using an OAuth app, we recommend [registering SonarQube Server as a GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app) and following the configuration steps below. For general information on the differences between OAuth apps and GitHub Apps, see the [GitHub documentation](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps).
{% endhint %}

## Registering SonarQube Server as a GitHub App for authentication and provisioning <a href="#registering-sonarqube-as-a-github-app-for-authentication-and-provisioning" id="registering-sonarqube-as-a-github-app-for-authentication-and-provisioning"></a>

First, [register SonarQube Server as a GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app). If you already use a GitHub App for instance binding, you can reuse it for user authentication and provisioning. See [Setting up a GitHub App](/sonarqube-server/2025.1/devops-platform-integration/github-integration/setting-up-at-global-level/setting-up-github-app.md).

Configure the following settings in your GitHub App:

* **General** tab:
  * **Homepage URL**: The URL of your SonarQube Server instance. For example, `https://sonarqube.mycompany.com`. For security reasons, HTTP is not supported. You must use HTTPS. The URL must also be configured in SonarQube Server. See [Server base URL](/sonarqube-server/2025.1/instance-administration/server-base-url.md).
  * **Callback URL**: The URL of your SonarQube Server. For example, `https://sonarqube.mycompany.com`.
  * **Webhooks**: Disable this feature.
* **Permissions & events** tab:

| **Permission**                            | **Access** | **Comment**                                                                                                    |
| ----------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------- |
| Repository permissions > Administration   | Read-only  | <p>Only for automatic provisioning.</p><p>After saving, the App owner must validate the permission change.</p> |
| Organization permissions > Administration | Read-only  | <p>Only for automatic provisioning.</p><p>After saving, the App owner must validate the permission change.</p> |
| Organization Permissions > Members        | Read-only  | <p><br></p>                                                                                                    |
| Account permissions > Email addresses     | Read-only  | <p><br></p>                                                                                                    |

* **Install App** tab: Click **Install** and confirm the installation in 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 users need to authenticate or be provisioned from several organizations. Then list those organizations as allowed organizations in SonarQube Server.

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

**Step 1**: In SonarQube Server, go to **Administration** > **Configuration** > **General Settings** > **Authentication** > **GitHub**, then click **Create configuration**.

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

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

**Step 3:** Fill in the **API URL** and **Web URL** fields with the values recommended by GitHub.

**Step 4:** If your GitHub App is public, enter the allowed organizations in the **Organizations** field.

{% hint style="warning" %}
For automatic provisioning, not entering the allowed organizations for a public App can let unwanted users authenticate to your SonarQube Server instance, because anyone can install a public GitHub App.

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 Server instance, even if the GitHub App used for authentication is private.
{% endhint %}

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

## Choosing the provisioning method <a href="#choosing-the-provisioning-method" id="choosing-the-provisioning-method"></a>

Once you’ve set up your GitHub configuration, choose how users and groups are provisioned to SonarQube Server. For an overview of the available provisioning methods, see [Overview of authentication and provisioning](/sonarqube-server/2025.1/instance-administration/authentication/overview.md).

**Step 1:** In SonarQube Server, 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 the first time they authenticate through GitHub, if **Allow users to sign up** is enabled.
    * User information and group memberships are updated at each authentication.
    * Optionally, enable **Synchronize teams as groups** to synchronize GitHub teams with existing SonarQube Server groups that use the same name.
    * Before enabling this option, create or verify the groups in SonarQube Server as described in **Just-in-Time provisioning** > **Group synchronization** in [Overview of authentication and provisioning](/sonarqube-server/2025.1/instance-administration/authentication/overview.md).
  * **Automatic user, group, and permission provisioning** (starting in [Developer Edition](https://www.sonarsource.com/plans-and-pricing/developer/))
    * Users and groups synchronize hourly. The first synchronization starts immediately when you enable the feature.
    * Permissions are also synchronized. See below for more information.
    * You can check the synchronization status on this configuration page in the **Automatic user and group provisioning** box.
    * If needed, you can manually trigger a synchronization by clicking **Synchronize now**.
    * Groups in SonarQube Server are named after GitHub organizations and teams, in the format *Organization/Team*.
    * A user’s email address is updated only when no address is set in SonarQube Server. Once an address is set, it is updated only when the user authenticates.

**Step 3:** When you change a setting, you can validate the configuration by clicking **Test configuration**.

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

Users can now sign in to SonarQube Server from the login page with the **Log in with GitHub** button.

## About user permission synchronization <a href="#about-user-permission-synchronization" id="about-user-permission-synchronization"></a>

With automatic provisioning, project-level user and group permissions also synchronize from GitHub. Synchronization runs regularly and automatically adds or removes permissions in SonarQube Server.

As part of permission synchronization, you can also synchronize project visibility by enabling the **Provision project visibility** option.

* When enabled, your SonarQube Server project’s visibility will match the corresponding GitHub repository’s visibility.
* When disabled, your SonarQube Server project’s visibility will be set to private, regardless of the GitHub repository’s visibility.

For all GitHub-managed users, permissions can no longer be edited on GitHub-managed SonarQube Server projects. Manage permission changes directly in GitHub.

### Permission mapping <a href="#permission-mapping" id="permission-mapping"></a>

SonarQube Server applies a default permission mapping that covers most use cases. If you need more control, you can customize this mapping so each GitHub **Direct access** role grants exactly the SonarQube Server permissions you want. You can also configure permission mapping for GitHub custom roles.

To do this, click **Edit mapping** in the automatic provisioning section.

Here is the default permission mapping. The first column lists the GitHub **Direct access** role, and the first row lists the SonarQube Server permissions.

![](/files/wSi9mqUThmlDfs6gk5Fd)

{% hint style="info" %}
**Known limitation (GitHub Enterprise only):** When a nested team has a custom role that extends the same base role as its parent team’s custom role, the nested team will use its parent’s custom role instead of its own.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sonarsource.com/sonarqube-server/2025.1/instance-administration/authentication/github.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.