Setting up a GitHub App to integrate SonarQube Community Build with GitHub
You need to use a GitHub App to connect SonarQube Community Build with a GitHub instance in order to be able to use the following features:
- Importing your GitHub repositories into SonarQube Community Build.
- Delegating the SonarQube Community Build user authentication to GitHub.
You need the global Administer System permission in SonarQube Community Build to perform this setup.
Setup overview
The SonarQube Community Build uses the GitHub App to access GitHub resources as illustrated below. The GitHub resources access permissions are set in the App. A "GitHub Configuration" record is used in SonarQube Community Build to access the GitHub App. A different Configuration is used to manage the repository import and the user authentication.
To set up a GitHub App to integrate SonarQube Community Build with GitHub:
- Register a GitHub App for SonarQube Community Build.
- Install the App on the organizations SonarQube Community Build needs to access.
- Add the App to SonarQube Community Build'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 SonarQube Community Build as a GitHub App.
See GitHub's documentation on registering a GitHub App for general information on GitHub Apps.
We recommend registering a public app using the procedure below. However, if you have only one GitHub organization, you can register a private app under that organization.
Specify the following settings in your app:
- GitHub App Name: Your app's name. Example: sonarqubeserver.
- Homepage URL: Your SonarQube Community Build instance's base URL (for information purposes only).
- Callback URL: Your SonarQube Community Build instance's base URL (the URL used to redirect to the SonarQube Community Build).
- Webhook URL: To improve security, webhooks, by default, are not allowed to point to the SonarQube Community Build. Therefore, we recommend that you disable the feature. 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 |
|---|---|---|
| Checks | Read & Write | |
| Administration | Read-only | Required only for user provisioning. |
GitHub Enterprise: Repository metadata GitHub.com: Metadata | Read-only | |
| Private repositories: Content | Read-only |
Organization permissions
| Permission | Access | Note |
|---|---|---|
| Administration | Read-only | Required only for user provisioning. |
| Members | Read-only | |
| Projects | Read-only |
Account permissions
| Permission | Access | Note |
|---|---|---|
| Email addresses | Read-only | Required only for user authentication and provisioning. |
- 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 Community Build on your organization(s)
You need to install the GitHub App for SonarQube Community Build on the GitHub organizations that SonarQube Community Build will need to access. See GitHub's documentation on installing GitHub Apps for more information.
Step 3: Add the GitHub App to SonarQube Community Build's global setup
You need to create a GitHub Configuration record in SonarQube Community Build 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 Community Build's global setup for repository import:
- In the SonarQube UI, go to Administration > Configuration > General Settings > DevOps Platform Integrations.
- Select the GitHub tab and click Create configuration. The New GitHub configuration dialog opens.
- Specify the settings: see Configuration settings below.
If you want to delegate the user authentication to GitHub
To add the GitHub App to SonarQube Community Build's global setup for user delegation, go to Administration > Configuration > General Settings > Authentication > GitHub. See Connecting your GitHub App to SonarQube Community Build in GitHub authentication.
Configuration settings
| Field | Description | Note |
|---|---|---|
| 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 Encrypting 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 Encrypting sensitive settings. |
Was this page helpful?
© 2008-2025 SonarSource SA. All rights reserved. SONAR, SONARSOURCE, SONARQUBE, and CLEAN AS YOU CODE are trademarks of SonarSource SA.
