> 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-community-build/devops-platform-integration/github-integration/setting-up-at-global-level/setting-up-github-app.md).

# Setting up a GitHub App

Setting up a GitHub App for use with SonarQube Community Build.

You need to use a GitHub App to connect SonarQube Community Build with a GitHub instance in order to use the following features:

* [Importing your GitHub repositories](/sonarqube-community-build/devops-platform-integration/github-integration/importing-github-repositories.md) into SonarQube Community Build.
* [Delegating the SonarQube Community Build user authentication](/sonarqube-community-build/instance-administration/authentication/github.md) to GitHub.

You need the global Administer System permission in SonarQube Community Build to perform this setup.

You can also open the **DevOps Platform Integrations** page from **Administration** > **Project coverage**. See the [Project coverage](/sonarqube-community-build/project-coverage.md) page.

## Setup overview <a href="#overview" id="overview"></a>

The setup consists of three stages:

1. Create or register a GitHub App using one of two methods:
   * **Configure manually**: You register and configure the app on GitHub yourself, then enter the credentials in SonarQube Community Build. Use this path if your network configuration prevents the automatic flow or if you already have a GitHub App you want to reuse.
   * **Create GitHub App** (recommended): SonarQube generates a preconfigured app and redirects you to GitHub to authorize its creation. SonarQube saves the resulting credentials automatically. Organization Owners complete the installation directly. Organization Members can initiate the flow, but an Owner must approve the installation to complete it.
2. [Install the app](#install-github-app-on-organization) on the GitHub organizations that SonarQube Community Build needs to access.
3. [Add the app to SonarQube Community Build's global setup](#add-github-app-to-sonarqube-setup).

## Create a GitHub App automatically <a href="#create-github-app-automatically" id="create-github-app-automatically"></a>

When you choose **Create GitHub App**, SonarQube creates the GitHub App with the required settings and permissions, and saves the credentials in SonarQube Community Build automatically. This method works with GitHub.com only. If you use GitHub Enterprise Server, see [Create a GitHub App manually](#create-github-app-manually).

### Prerequisite

You need a GitHub account with an organization Owner or Member role. If you are an organization Owner, you can create and install the app in one step. If you are an organization Member, GitHub sends an installation approval request to your organization Owners. The app is active in SonarQube Community Build once an Owner approves it.

Configure your instance's base URL before you create the app, because SonarQube uses it as the address GitHub redirects you back to. Use a fully qualified domain name, not localhost. See the [Configuring the SonarQube Community Build base URL](/sonarqube-community-build/instance-administration/server-base-url.md) page.

To create a GitHub App automatically:

1. In the SonarQube UI, go to **Administration** > **Configuration** > **General Settings** > **DevOps Platform Integrations**.
2. Open the **GitHub** tab and select **Create GitHub App**. The **Create a GitHub App** dialog opens.
3. Enter your **GitHub organization** and a unique **Configuration name**.
   * Optionally, select **Also set up GitHub authentication** to enable users to sign in using their GitHub login credentials. Selecting this shows the **Allowed organizations** field, prefilled with the value you entered in **GitHub organization**. You can add, change, or remove organizations before continuing.

     <div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><p>If you leave <strong>Allowed organizations</strong> empty, any user with a GitHub account can log in to SonarQube Community Build, even if the GitHub App used for authentication is private.</p></div>
4. Select **Continue to GitHub** to confirm access, after which GitHub's **Create GitHub App** page will open.
5. Add your GitHub App name and select **Create GitHub App for&#x20;*****Your GitHub Organization*** to continue. You can always change the app name later.
6. A new page will open where you must select the GitHub organization where you want to install the app.
7. Select either **All repositories** or **Only select repositories** to bind to SonarQube Community Build.
8. To complete the installation, select **Install & Authorize** to finish. GitHub will redirect you back to SonarQube Community Build. The App ID, Client ID, Client Secret, and Private Key are saved automatically in a new GitHub Configuration record.

SonarQube pre-configures the app with the following permissions, which are shown on GitHub for review:

* Read access to administration, code, members, metadata, organization administration, and organization projects.
* Read and write access to checks.
* Read access to email addresses (user permission).

After the app is created, [install it on your GitHub organizations](#install-github-app-on-organization).

{% hint style="warning" %}
If repository import fails, one reason might be that the app's Redirect URIs do not match what SonarQube sends. To fix this, an organization Owner or GitHub App manager must go to **Settings** > **Developer settings** > **GitHub Apps** > your app > **Basic information** > **Redirect URI** and either select **Allow wildcard matching** or make sure the three Redirect URIs described in [Create a GitHub App manually](#create-github-app-manually) are present.
{% endhint %}

### If the automatic flow fails

If the automatic flow fails (for example, because of network or firewall restrictions between SonarQube Community Build and GitHub), use the manual setup instead. See [Create a GitHub App manually](#create-github-app-manually).

## Create a GitHub App manually <a href="#create-github-app-manually" id="create-github-app-manually"></a>

Use manual setup if:

* Your SonarQube Community Build cannot complete the automatic flow (for example, because of network or firewall restrictions).
* You already have a GitHub App for SonarQube Community Build and want to reuse it.

If you already have a GitHub App, skip the registration steps below and go directly to [Add the GitHub App to SonarQube Community Build's global setup](#add-github-app-to-sonarqube-setup).

After registering a new app, continue with [Install the GitHub App in your organizations](#install-github-app-on-organization).

See GitHub's documentation on [registering a GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app) for general information on GitHub Apps.

We recommend registering a public App. You can register a private App if you have only one GitHub organization. In that case, you must register the 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).
* **Redirect URI**: Your SonarQube Community Build instance's base URL (the URL used to redirect to the SonarQube Community Build). GitHub requires the `redirect_uri` that SonarQube sends to match a configured Redirect URI exactly, and importing repositories fails if it does not. Use one of the following configurations, where `<YourBaseUrl>` is that base URL:

  * Enter `<YourBaseUrl>` and enable **Allow wildcard matching** for that Redirect URI.
  * Add three Redirect URIs without enabling wildcard matching: `<YourBaseUrl>`, `<YourBaseUrl>/oauth2/callback/github`, and `<YourBaseUrl>/projects/create`.

  <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>In GitHub Enterprise Server before 3.23, this field is called <strong>Callback URL</strong> and the <strong>Allow wildcard matching</strong> option does not exist. These versions do not require an exact match, so enter your base URL in <strong>Callback URL</strong>.</p></div>
* **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** and **Subscribe to events**, set up the permissions and events as explained below in the list of settings. Some permissions or events are only necessary depending on the purpose of the integration.

<details>

<summary>Permissions and events settings</summary>

**Repository permissions**

| Permission                                                                                              | Access       | Note                                 |
| ------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------ |
| Administration                                                                                          | Read-only    | Required only for user provisioning. |
| Checks                                                                                                  | Read & Write | <p><br></p>                          |
| Contents                                                                                                | Read-only    | <p><br></p>                          |
| <p><em>In GitHub Enterprise Server</em>: Repository metadata</p><p><em>In GitHub.com</em>: Metadata</p> | Read-only    | <p><br></p>                          |

**Organization permissions**

| Permission     | Access    | Note                                 |
| -------------- | --------- | ------------------------------------ |
| Administration | Read-only | Required only for user provisioning. |
| Members        | Read-only | <p><br></p>                          |
| Projects       | Read-only | <p><br></p>                          |

**Account permissions**

| Permission      | Access    | Note                                                    |
| --------------- | --------- | ------------------------------------------------------- |
| Email addresses | Read-only | Required only for user authentication and provisioning. |

</details>

* Under **Where can this GitHub App be installed?** select **Any account** to make the App public in order to allow you to install the App on any organization.

After registering the app, [install it on your GitHub organizations](#install-github-app-on-organization).

## Install the GitHub App in your organizations <a href="#install-github-app-on-organization" id="install-github-app-on-organization"></a>

Install the GitHub App on each GitHub organization that SonarQube Community Build needs to access. See GitHub's documentation on [installing GitHub Apps](https://docs.github.com/en/free-pro-team@latest/developers/apps/installing-github-apps) for more information.

## Add the GitHub App to SonarQube Community Build's global setup <a href="#add-github-app-to-sonarqube-setup" id="add-github-app-to-sonarqube-setup"></a>

If you chose **Create GitHub App**, SonarQube has already created a GitHub Configuration record for repository import. You only need to complete this step if you used the manual setup, or if you want to set up user authentication delegation.

<details>

<summary>If you want to support the GitHub repository import</summary>

To add the GitHub App to SonarQube Community Build's global setup for repository import:

1. In the SonarQube UI, go to **Administration** > **Configuration** > **General Settings** > **DevOps Platform Integrations**.
2. Select the **GitHub** tab and select **Configure manually**. The **Create a configuration** dialog opens.
3. Specify the settings in the [Configuration settings](#configuration-settings) section below.

</details>

<details>

<summary>If you want to delegate the user authentication to GitHub</summary>

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](/sonarqube-community-build/instance-administration/authentication/github.md).

</details>

<details>

<summary>Configuration settings</summary>

| **Field**      | **Description**                                                                                                                                                                                    | **Note**                                                                                                                                           |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| GitHub API URL | <p>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.</p><p><br></p>                          | <p><br></p>                                                                                                                                        |
| GitHub App ID  | The App ID of your GitHub App (on GitHub, go to Settings > Developer Settings > GitHub Apps to view your App).                                                                                     | <p><br></p>                                                                                                                                        |
| Client ID      | The Client ID of your GitHub App's page.                                                                                                                                                           | <p><br></p>                                                                                                                                        |
| Client Secret  | The Client secret of your GitHub App's page. Administrators can encrypt this secret, see [Sensitive settings](/sonarqube-community-build/instance-administration/security/encrypting-settings.md). | <p><br></p>                                                                                                                                        |
| 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 [Sensitive settings](/sonarqube-community-build/instance-administration/security/encrypting-settings.md). |

</details>


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.sonarsource.com/sonarqube-community-build/devops-platform-integration/github-integration/setting-up-at-global-level/setting-up-github-app.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.