SonarQube's integration with GitHub Enterprise and GitHub.com allows you to maintain code quality and security in your GitHub repositories.
With this integration, you'll be able to:
- Import your GitHub repositories: Import your GitHub repositories into SonarQube to easily set up SonarQube projects.
- Analyze projects with GitHub Actions: Integrate analysis into your build pipeline. Starting in Developer Edition, SonarScanners running in GitHub Actions jobs can automatically detect branches or pull requests being built so you don't need to specifically pass them as parameters to the scanner.
- Report your quality gate status to your branches and pull requests: (starting in Developer Edition) See your quality gate and code metric results right in GitHub so you know if it's safe to merge your changes.
- Authenticate with GitHub: Sign in to SonarQube with your GitHub credentials.
- To add pull request decoration to Checks in GitHub Enterprise, you must be running GitHub Enterprise version 2.21+.
- To analyze projects with GitHub Actions in GitHub Enterprise, you must be running GitHub Enterprise version 3.0+.
Community Edition doesn't support the analysis of multiple branches, so you can only analyze your main branch. With Developer Edition, you can analyze multiple branches and pull requests.
Importing your GitHub repositories to SonarQube
You need to use a GitHub App to connect SonarQube with GitHub and import your GitHub repositories into SonarQube. This is also the first step in adding authentication, and, starting in Developer Edition, the first step in reporting your analysis and quality gate status to your pull requests.
If you want to set up authentication without importing your GitHub repositories, see the Creating a dedicated app for authentication section below for instructions on setting up authentication.
In this section, you'll complete the following steps to connect SonarQube and GitHub with a GitHub App:
- Create your GitHub App.
- Install your GitHub App in your organization.
- Update your SonarQube global settings with your GitHub App information.
Step 1: Creating your GitHub app
See GitHub's documentation on creating a GitHub App for general information on creating your app.
Specify the following settings in your app:
- GitHub App Name: Your app's name.
- Homepage URL: You can use any URL, such as
- User authorization callback URL: Your instance's base URL. For example,
- Webhook URL: Your instance's base URL. For example,
- Grant access for the following Repository permissions:
|Checks||Read & write|
|GitHub Enterprise: Repository metadata|
(this setting is automatically set by GitHub)
|Pull Requests||Read & write|
- For private repositories, grant access to the following Repository permissions:
- If setting up GitHub Authentication, in addition to the aforementioned Repository permissions, grant access for the following User permissions:
- And grant access for the following Organization permissions:
- Under "Where can this GitHub App be installed?," select Any account.
For security reasons, make sure you're using
HTTPS protocol for your URLs in your app.
Step 2: Installing your GitHub app in your organization
Next, you need to install your GitHub App in your organization. See GitHub's documentation on installing GitHub Apps for more information.
Step 3: Updating your SonarQube global settings with your GitHub app information
After you've created and installed your GitHub App, update your global SonarQube settings to finish integration and allow for the import of GitHub projects.
Navigate to Administration > Configuration > General Settings > DevOps Platform Integrations > GitHub and specify the following settings:
- Configuration Name (Enterprise and Data Center Edition only): The name used to identify your GitHub configuration at the project level. Use something succinct and easily recognizable.
- GitHub URL: For example,
https://github.company.com/api/v3for GitHub Enterprise or
- GitHub App ID: The App ID is found on your GitHub App's page on GitHub at Settings > Developer Settings > GitHub Apps.
- Client ID: The Client ID is found on your GitHub App's page.
- Client secret: The Client secret is found on your GitHub App's page. Administrators can encrypt this secret at Administration > Configuration > Encryption. See the Settings Encryption section of the Security page for more information.
- Private Key: Your GitHub App's private key. You can generate a
.pemfile from your GitHub App's page under Private keys. Copy and paste the whole contents of the file here. Administrators can encrypt this key at Administration > Configuration > Encryption. See the Settings Encryption section of the Security page for more information.
Analyzing projects with GitHub Actions
SonarScanners running in GitHub Actions can automatically detect branches and pull requests being built so you don't need to specifically pass them as parameters to the scanner.
To analyze your projects with GitHub Actions, you need to:
- Create your GitHub Secrets.
- Configure your workflow YAML file.
- Commit and push your code to start the analysis.
Creating your GitHub secrets
You can create repository secrets from your GitHub repository. See GitHub's documentation on Encrypted secrets for more information.
You need to set the following GitHub repository secrets to analyze your projects with GitHub Actions:
- Sonar Token: Generate a SonarQube token and, in GitHub, create a new repository secret in GitHub with
SONAR_TOKENas the Name and the token you generated as the Value.
- Sonar Host URL: In GitHub, create a new repository secret with
SONAR_HOST_URLas the Name and your SonarQube server URL as the Value.
Configuring your .github/workflows/build.yml file
This section shows you how to configure your
You'll set up your build according to your SonarQube edition:
- Community Edition: Community Edition doesn't support multiple branches, so you should only analyze your main branch. You can restrict analysis to your main branch by setting it as the only branch in your
on.push.branchesconfiguration in your workflow YAML file, and not using
- Developer Edition and above: GitHub Actions can build specific branches and pull requests if you use
on.pull-requestsconfigurations as shown in the examples below.
Click the scanner you're using below to expand the example configuration:
Failing the pipeline job when the quality gate fails
If you do not want to use the SonarQube quality gate Check Action, you can instruct the scanner to wait for the SonarQube quality gate status at the end of the analysis. To enable this, pass the
-Dsonar.qualitygate.wait=true parameter to the scanner in the workflow YAML file.
This will make the analysis step poll SonarQube regularly until the quality gate is computed. This will increase your pipeline duration. Note that, if the quality gate is red, this will make the analysis step fail, even if the actual analysis itself is successful. We advise only using this parameter when necessary (for example, to block a deployment pipeline if the quality gate is red). It should not be used to report the quality gate status in a pull request, as this is already done with pull request decoration.
You can set the
sonar.qualitygate.timeout property to an amount of time (in seconds) that the scanner should wait for a report to be processed. The default is 300 seconds.
Commit and push your code
Commit and push your code to start the analysis. Each new push you make on your branches or pull requests will trigger a new analysis in SonarQube.
Reporting your quality gate status in GitHub
After creating and installing your GitHub App above, SonarQube can report your quality gate status and analysis metrics directly to your GitHub branches and pull requests.
To do this, add a project from GitHub by clicking the Add project button in the upper-right corner of the Projects homepage and select GitHub from the drop-down menu.
Then, follow the steps in SonarQube to analyze your project. SonarQube automatically sets the project settings required to show your quality gate in your branches and pull requests.
To report your quality gate status in your branches and pull requests, a SonarQube analysis needs to be run on your code. You can find the additional parameters required for pull request analysis on the Pull Request Analysis page.
If you're creating your projects manually or adding quality gate reporting to an existing project, see the following section.
Reporting your quality gate status in manually created or existing projects
SonarQube can also report your quality gate status to GitHub pull requests and branches for existing and manually-created projects. After you've created and installed your GitHub App and updated your global DevOps Platform Integration settings as shown in the Importing your GitHub repositories into SonarQube section above, set the following project settings at Project Settings > General Settings > DevOps Platform Integration:
- Configuration name: The configuration name that corresponds to your GitHub instance.
- Repository identifier: The path of your repository URL.
Authenticating with GitHub
To allow users to log in with GitHub credentials, use the GitHub App that you created above (see the Importing your GitHub repositories using a GitHub app section for more information) and update your global SonarQube settings.
If you're using Community Edition or you want to use a dedicated app for GitHub authentication, see the Creating a dedicated app for authentication section below.
To update your global SonarQube settings:
Navigate to Administration > Configuration > General Settings > DevOps Platform Integrations > GitHub > GitHub Authentication and update the following:
- Enabled: set the switch to
- Client ID: the Client ID is found below the GitHub App ID on your GitHub App's page.
- Client secret: the Client secret is found below the Client ID on your GitHub App's page.
Now, from the login page, your users can connect their GitHub accounts with the new "Log in with GitHub" button.
Creating a dedicated app for authentication
If you want to use a dedicated app for GitHub authentication, you can create a GitHub OAuth app. You'll find general instructions for creating a GitHub OAuth App here. Specify the following settings in your OAuth App:
- 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.
- Authorization callback URL: your instance's base URL. For example,
After creating your app, follow the steps immediately above to update your global SonarQube settings.
© 2008-2022, SonarSource S.A, Switzerland. Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution-NonCommercial 3.0 United States License. SONARQUBE is a trademark of SonarSource SA. All other trademarks and copyrights are the property of their respective owners.