> 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-cloud/administering-sonarcloud/managing-organization/creating-organization/importing-ghecom-cloud-organization.md).

# Importing GHE.com Cloud organization

This feature is available in the [Enterprise](https://www.sonarsource.com/plans-and-pricing/) plan.

When you import your GitHub Enterprise Cloud with Data Residency (GHE) organization to your SonarQube Cloud enterprise, the corresponding organization is created in SonarQube Cloud and is bound to the DevOps platform organization. See [Binding with the DevOps platform](/sonarqube-cloud/administering-sonarcloud/about-sonarqube-cloud-solution/resources-structure/binding-with-dop.md) for more information.

The user account you used for the import is automatically assigned to the organization's owners group which grants you administration rights on the organization. See [User group concept](/sonarqube-cloud/administering-sonarcloud/about-sonarqube-cloud-solution/user-management/user-group-concept.md) for more details.

Notes:

* If you are [Creating your enterprise](/sonarqube-cloud/administering-sonarcloud/managing-enterprise/creating-your-enterprise.md) first, create an organization manually during that flow and subsequently bind it to your GHE.com organization.
* For more information about the GHE.com Cloud integration solution and its current limitations, see [GitHub](/sonarqube-cloud/discovering-sonarcloud/integration-with-devops-platforms/github.md).

## Prerequisites

* Your SonarQube Cloud enterprise exists and you're an admin of it.
* You are an admin/owner of the GHE.com Cloud organization.
* If your GHE.com Cloud organization enforces a strict IP allow list, you must allow SonarQube Cloud access as described in [Networking requirements](/sonarqube-cloud/appendices/networking-requirements.md#if-using-github-enterprise-clouds-ip-allow-list).

## Step 1: Create your GHE application <a href="#step-1" id="step-1"></a>

You must first create the GHE application that will be used by SonarQube Cloud to authenticate to your GHE.com Cloud organization.

### Create the app

1. Inside GHE, go to the organization you want to import to SonarQube Cloud.
2. Open the **Settings** tab.

<figure><img src="/files/W2u6RdnqUwJSJGiXGMD2" alt="A screenshot of a GitHub organization&#x27;s settings page, specifically the General tab. The Settings tab in the top navigation bar is highlighted."><figcaption></figcaption></figure>

3. In the left panel, scroll down to the bottom of the menu and select **Developer Settings > GitHub Apps**. The **GitHub Apps** page opens.

<figure><img src="/files/BaDdXwqQFfuUdFyQwgYL" alt="A screenshot of GitHub Developer Settings, showing a list of GitHub Apps. The New GitHub App button is highlighted."><figcaption></figcaption></figure>

4. Select the **New GitHub App** button in the top right corner. The **Create GitHub App** page opens.

<figure><img src="/files/Edr3XFHuj3NY3Y8EONY7" alt="A screenshot of the Create GitHub App page, highlighting the input fields for GitHub App name and Homepage URL."><figcaption></figcaption></figure>

5. Fill in the following mandatory fields:
   * **GitHub App name**: A name you choose for your app that's easily identifiable.
   * **Homepage URL**: Your SonarQube Cloud's server base URL (for information purposes only). Example: <https://sonarcloud.io>. Or <https://sonarqube.us>
6. In the **Webhook** section, select **Active** and fill in the webhook parameters.
   1. For EU it is: <https://api.sonarcloud.io/github-events-dispatcher/ghec>
   2. For US it is: <https://api.sonarqube.us/github-events-dispatcher/ghec>
7. Create a **Webhook Secret**. To create a secret, enter a value [following the GitHub documentation](https://docs.github.com/en/webhooks/using-webhooks/best-practices-for-using-webhooks#use-a-webhook-secret) best practices. You'll need the Webhook secret in Step 3.
8. In the **Permissions** section, set the **Repository** permissions as follows:
   * **Checks**: Read & Write
   * **Contents**: Read
   * **Metadata**: Read
   * **Pull requests**: Read & Write
   * **Code scanning alerts (Optional)**: Read & Write — we recommend enabling this now to avoid reconfiguring permissions when new features are released
9. In **Subscribe to events**, select the following event types: **Pull request**, **Push**, **Repository**, and **Code scanning alert** (optional — enable now to avoid reconfiguring events when new features are released).
10. In **Where can this GitHub App be installed?** section at the bottom, select **This enterprise** if you want your app to be reused by multiple organizations, or **Only on this account** otherwise.
11. Select the **Create GitHub App** button at the bottom of the page. Your app is created.

<figure><img src="/files/KeZLWwf5OqfHIkeKZrNQ" alt="A screenshot of GitHub developer settings showing the About section for an app. The App ID is highlighted."><figcaption></figcaption></figure>

The App page displays the **App ID** you'll need in Step 3.

12. Navigate down to **Private keys**, and select **Generate a private key**. A private key in PEM format is downloaded to your computer. You'll need this file in Step 3.

<figure><img src="/files/B6gyOrAaasFqw3XiZgYT" alt="A user interface screen titled Private keys that prompts the user to Generate a private key to sign access token requests."><figcaption></figcaption></figure>

13. Don't leave the page and go to Step 2.

## Step 2: Install your app to your GHE organization <a href="#step-2" id="step-2"></a>

1. From the app you created in your GHE organization, select **Install App** in the left menu. The **Install \<app>** page opens.

<figure><img src="/files/gMQdESnSIKyNrHcc2FjR" alt="A screenshot demonstrating how to install an application, with the Install App option highlighted in the left navigation menu and the Install button highlighted on the right."><figcaption></figcaption></figure>

2. Select the **Install** button in front of your GHE organization. You're redirected to the app installation page.

<div align="left"><figure><img src="/files/90Nx3bJWMU77KapnPEme" alt="A screenshot demonstrating the installation process for the SonarCloud App on a GitHub organization. It shows options to install on all repositories or select specific ones, along with required permissions." width="338"><figcaption></figcaption></figure></div>

3. The app configuration page opens. The browser URL shows two fields you'll need in the next step:
   1. **Web URL**: your enterprise's URL. It should look like <https://enterprise-name.ghe.com>
   2. **Installation ID**: The number at the end of the URL, after /installations/.

## Step 3: Import your GHE.com organization <a href="#step-3" id="step-3"></a>

1. Log in to SonarQube Cloud with your enterprise admin account and navigate to your SonarQube Cloud enterprise. See [Retrieving and viewing your enterprise](/sonarqube-cloud/administering-sonarcloud/managing-enterprise/retrieving-and-viewing-your-enterprise.md).
2. You arrive in **Organizations**. Select **Create organization** in the header. The **Create an organization** page opens.

<figure><img src="/files/Dy6v84aMBZSIB4MwlONC" alt="A screenshot of the SonarQube Cloud interface, demonstrating the Create an organization page. It shows options to import from various DevOps platforms like GitHub, GitLab, Bitbucket, and Azure DevOps."><figcaption></figcaption></figure>

3. Under **GitHub**, select **GHE.com Cloud**. The **GitHub app details** step opens.
4. Fill in the fields as follows:
   1. **Web URL**: Your enterprise's URL as retrieved in [Step 2 > 3.a](#step-2).
   2. **Installation ID**: The number retrieved in [Step 2 > 3.b](#step-2).
5. Check the auto-filled **Enterprise name** & **API URL** field.
6. Select the **Choose file** button under **Private Key**, and navigate to and select the private key file you generated in [Step 1 > 11](#step-1).
7. In **App ID**, enter the **App ID** value you retrieved in [Step 1 > 10](#step-1).
8. In **Webhooks secret**, enter the secret you created in [Step 1 > 7](#step-1).
9. Select **Confirm details**.

<figure><img src="/files/rOrir2meHtuEF6nQwY5L" alt="A screenshot of the SonarQube Cloud interface, demonstrating the Create an organization form. It specifically shows the section for configuring a GitHub Enterprise Cloud (with data residency) application, with fields for Web URL, Enterprise name, API URL, Application ID, and Private key."><figcaption></figcaption></figure>

## Updating the GHE app details in SonarQube Cloud <a href="#updating-the-ghe-app-details" id="updating-the-ghe-app-details"></a>

To modify in your SonarQube Cloud organization the details of the GHE application used to import your GHE.com Cloud organization:

1. Retrieve your SonarQube Cloud organization. See [Retrieving your organizations](/sonarqube-cloud/getting-started/viewing-organizations.md) for more information.
2. Go to **Administration > Organization settings > Organization binding**.
3. In **Application details**, press **Edit**. For information about the parameters, see [Step 3: Import your GHE.com organization](#step-3).

<figure><img src="/files/tAL9vQ1A8iUTk8oj4ql9" alt="A screenshot of the SonarQube Cloud organization settings page, specifically showing the Organization binding section. It details the current binding between SonarQube Cloud and a DevOps organization, and displays application connection details including Web URL, API URL, Application ID, and Installation ID. The Application connection verified status is highlighted."><figcaption></figcaption></figure>

## Rotating the GHE app's private key <a href="#rotating-the-private-key" id="rotating-the-private-key"></a>

To rotate the private key used by SonarQube Cloud to authenticate to GHE, proceed as follows:

1. Generate a new private key:
   1. Retrieve your GHE app.
   2. Under **Private keys**, select **Generate a private key**. A private key in PEM format is downloaded to your computer.
2. In SonarQube Cloud, edit the organization binding as described in [Updating the GHE app details in SonarQube Cloud](#updating-the-ghe-app-details).
3. In **Private key**, select your private key file.

## Rotating the GHE app's webhook secret

To rotate the secret used by your [GHE.com](http://ghe.com) enterprise to send webhooks to SonarQube Cloud, proceed as follows:

Attention: Updating the webhook secret is a time-sensitive procedure that can result in missed webhook events. We recommend executing these steps during periods of minimal activity and ensuring simultaneous access to both platforms before beginning.

1. In SonarQube Cloud, edit the organization binding as described in [Updating the GHE app details in SonarQube Cloud](#updating-the-ghe-app-details) and input the new secret value.
2. Within your GHE app configuration, navigate to the **Webhook** area, click **Change secret**, and enter the updated webhook secret.
3. Save the new value in SonarQube Cloud, then quickly save the value in your GHE app configuration.

## Troubleshooting

### GitHub App is missing required permissions

Grant your GHE app the missing permissions as follows:

1. Retrieve your GHE app.
2. Go to **Permissions & events**.
3. Make sure the following permissions in [Step 1 > 7](#step-1) of Create an app.
4. Save.

### Could not reach GitHub API

SonarQube Cloud cannot connect to the GitHub API URL. In that case, check the following:

1. The API URL field value is correct.
2. The GHE hostname is reachable.
3. Your firewall does not block outbound traffic from SonarQube Cloud to your GHE. See [Networking requirements](/sonarqube-cloud/appendices/networking-requirements.md#if-using-github-enterprise-clouds-ip-allow-list) for more information.

### Your GitHub organization has an IP allowlist that is blocking SonarQube Cloud

See [Networking requirements](/sonarqube-cloud/appendices/networking-requirements.md#if-using-github-enterprise-clouds-ip-allow-list).

### GitHub app validation failed <a href="#github-app-validation-failed" id="github-app-validation-failed"></a>

Verify that your app is not suspended:

1. Retrieve your GHE app. In the **Danger zone**, check if the app is suspended.
2. If it's the case, select **Unsuspend**.

<figure><img src="/files/LiBzFuln7h7kSVUeOcbf" alt="A screenshot of an application&#x27;s settings page, showing the Permissions and Danger zone sections. The Danger zone provides options to Suspend your installation and Uninstall."><figcaption></figcaption></figure>

### Your private key is not a valid .pem file

Change the key as described in [Rotating the GHE app's private key](#rotating-the-private-key).

### Your App ID or private key is invalid

Make sure the correct private key file is stored in SonarQube Cloud. To change the private key, see [Rotating the GHE app's private key](#rotating-the-private-key).

### Your App ID was not found on GitHub

Check that the application ID stored in SonarQube Cloud is correct:

1. Retrieve your GHE app and copy the **App ID**.
2. In SonarQube Cloud, edit the organization binding as described in [Updating the GHE app details in SonarQube Cloud](#updating-the-ghe-app-details) and paste the copied value to **App ID**.

### Your installation ID was not found or does not belong to this GitHub app

Make sure that the installation ID stored in SonarQube Cloud organization is correct:

1. In your GHE organization, go to the **GitHub Apps** page.
2. In front of the SonarQube Cloud app, select **Configure**.
3. Copy the **Installation ID** field value.
4. In SonarQube Cloud, edit the organization binding as described in [Updating the GHE app details in SonarQube Cloud](#updating-the-ghe-app-details) and paste the copied value to **Installation ID**.

### SonarQube Cloud cannot find your GHE.com Cloud organization

If SonarQube Cloud can't locate your organization during import, perform the following checks:

1. Make sure you're an administrator of the organization.
2. If the organization has a GitHub Enterprise Cloud IP allow list enabled, make sure SonarQube Cloud has access. See [Networking requirements](/sonarqube-cloud/appendices/networking-requirements.md#if-using-github-enterprise-clouds-ip-allow-list) for the steps to allow SonarQube Cloud access.
3. Double check your SonarQube Cloud app configuration.
4. Make sure your SonarQube Cloud app is not suspended as described in [GitHub app validation failed](#github-app-validation-failed).


---

# 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, and the optional `goal` query parameter:

```
GET https://docs.sonarsource.com/sonarqube-cloud/administering-sonarcloud/managing-organization/creating-organization/importing-ghecom-cloud-organization.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.