Importing GHE.com Cloud organization

Learn how to import your GHE.com Cloud organization into your existing SonarQube Cloud enterprise.

This feature is available in the Enterprise 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 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 for more details.

Notes:

• If you are Creating your enterprise first, you can select GHE.com Cloud during that flow to create the SonarQube Cloud organization and bind it directly to your GHE.com organization.
• For more information about the GHE.com Cloud integration solution and its current limitations, see GitHub.

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 If using GitHub Enterprise Cloud's IP allow list.

Step 1: Create your GHE application

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.

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

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

1. 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). Enter https://sonarcloud.io for the EU region or https://sonarqube.us for the US region.
2. In the Webhook section, select Active and fill in the webhook parameters.

   • For EU it is: https://api.sonarcloud.io/github-events-dispatcher/ghec
   • For US it is: https://api.sonarqube.us/github-events-dispatcher/ghec
3. Create a Webhook Secret. To create a secret, enter a value following the GitHub documentation best practices. You'll need the Webhook secret in Step 3.
4. 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
5. 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).
6. 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.
7. Select the Create GitHub App button at the bottom of the page. Your app is created. The App page displays the App ID you'll need in Step 3.

1. 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.

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

Step 2: Install your app to your GHE organization

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

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

1. The app configuration page opens. The browser URL shows two fields you'll need in Step 3: a. Web URL: your enterprise's URL. It should look like https://enterprise-name.ghe.com b. Installation ID: the number at the end of the URL. For example, if your URL is https://enterprise-name.ghe.com/organizations/my-org/settings/installations/66, then the installation ID is 66.

Step 3: Import your GHE.com organization

1. Log in to SonarQube Cloud with your enterprise admin account.
2. Select your account menu in the top right corner, then under My Enterprises, select your enterprise. The Organizations page of the enterprise opens. See Retrieving and viewing your enterprise for more details.

GHE.com organizations must be created from your enterprise's Organizations page. The + menu > Create new organization flow does not support GHE.com.

1. On the Organizations page, select Create new organization. The Create an organization page opens.

1. Under GitHub, select GHE.com Cloud. The GitHub app details step opens.

1. Fill in the fields as follows:

   • Web URL: Your enterprise's URL as retrieved in Step 2 > 3.a.
   • Installation ID: The number retrieved in Step 2 > 3.b.
2. Check the auto-filled Enterprise name & API URL field.
3. Select the Choose file button under Private Key, and navigate to and select the private key file you generated in Step 1 > 12.
4. In App ID, enter the App ID value you retrieved in Step 1 > 11.
5. In Webhooks secret, enter the secret you created in Step 1 > 7.
6. Select Confirm details.

Updating the GHE app details in SonarQube Cloud

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 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.

Rotating the GHE app's private key

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

1. Generate a new private key: a. Retrieve your GHE app. b. 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.
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 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 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 required permissions are set as described in Step 1 > 8 of Create the 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 If using GitHub Enterprise Cloud's IP allow list for more information.

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

See If using GitHub Enterprise Cloud's IP allow list.

GitHub app validation failed

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.

Your private key is not a valid .pem file

Change the key as described in Rotating the GHE app's 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.

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 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 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 If using GitHub Enterprise Cloud's 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.

Automatic analysis, automatic project import, or branch renaming is not working

These features rely on webhook events from GHE.com. Verify your GHE app's webhook configuration:

1. Make sure the webhook is active and its URL matches your SonarQube Cloud region. See Step 1: Create your GHE application.
2. Make sure the webhook secret in your GHE app matches the Webhooks secret stored in the SonarQube Cloud organization binding. See Updating the GHE app details in SonarQube Cloud.
3. Follow GitHub's instructions to view recent webhook deliveries and check that events are being delivered to the configured SonarQube Cloud webhook URL.

A successful delivery confirms that the webhook request reached SonarQube Cloud. It does not confirm that the webhook secret is correct. If the secrets configured in GHE.com and SonarQube Cloud do not match, SonarQube Cloud receives the request but cannot validate its signature. The event is rejected and webhook-dependent features are not triggered.