GitHub

Setting up the GitHub authentication in your SonarQube Server instance.

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.

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 and following the configuration steps below. For general information on the differences between OAuth apps and GitHub Apps, see the GitHub documentation.

Registering SonarQube Server as a GitHub App for authentication and provisioning

First, register SonarQube Server as 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.

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.
  • 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	Only for automatic provisioning. After saving, the App owner must validate the permission change.
Organization permissions > Administration	Read-only	Only for automatic provisioning. After saving, the App owner must validate the permission change.
Organization Permissions > Members	Read-only
Account permissions > Email addresses	Read-only

• 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

1. In SonarQube Server, go to Administration > Configuration > General Settings > Authentication > GitHub, then click Create configuration.
2. Fill in the following fields with information from your GitHub App:

   • Client ID
   • Client Secret
   • GitHub App ID
   • Private Key
3. Fill in the API URL and Web URL fields with the values recommended by GitHub.
4. If your GitHub App is public, enter the allowed organizations in the Organizations field.

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.

1. Click Save configuration.

Choosing the provisioning method

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.

1. In SonarQube Server, from the Authentication > GitHub tab, click Enable configuration.
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.
   • Automatic user, group, and permission provisioning (starting in Developer Edition)

     • 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.
3. When you change a setting, you can validate the configuration by clicking Test configuration.
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

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

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.

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.

Related online learning

• Integrating SonarQube Server with GitHub for authentication and authorization