From 277774059792a8e27971243e46d0961fdd44bac8 Mon Sep 17 00:00:00 2001 From: MikeBirnstiehl <47737412+MikeBirnstiehl@users.noreply.github.com> Date: Wed, 13 Mar 2019 09:50:22 +0100 Subject: [PATCH] SONAR-11769 Update docs for GHE PR analysis --- .../src/pages/analysis/pull-request.md | 34 +++++------ .../github-application.md | 58 +++++++++++++++++++ .../src/pages/requirements/requirements.md | 5 ++ .../static/SonarQubeNavigationTree.json | 1 + .../static/StaticNavigationTree.json | 1 + 5 files changed, 80 insertions(+), 19 deletions(-) create mode 100644 server/sonar-docs/src/pages/instance-administration/github-application.md diff --git a/server/sonar-docs/src/pages/analysis/pull-request.md b/server/sonar-docs/src/pages/analysis/pull-request.md index 34d94992eda..b8c887e3ce5 100644 --- a/server/sonar-docs/src/pages/analysis/pull-request.md +++ b/server/sonar-docs/src/pages/analysis/pull-request.md @@ -43,33 +43,29 @@ These parameters enable PR analysis: ### Pull Request Decoration To activate PR decoration, you need to: -* declare an Authentication Token -* specify the Pull Request provider -* feed some provider-specific parameters +* (For GitHub Enterprise) Specify your pull request provider, create a GitHub App and configure your SonarQube instance, and set your GitHub parameters. +* (For Azure DevOps and Bitbucket) Specify your pull request provider and set an authentication token/personal access token. -#### Authentication Token - -The first thing to configure is the authentication token that will be used by {instance} to decorate the PRs. This can be configured in **Administration > General Settings > Pull Requests**. The field to configure depends on the provider. -For GitHub Enterprise or GitHub.com, you need to configure the **Authentication token** field. For Azure DevOps or Bitbucket Server, this is the **Personal access token**. - - -If you are using Azure DevOps, the first thing to configure is the authentication token that will be used by {instance} to decorate the PRs. This can be configured in **Administration > General Settings > Pull Requests > VSTS > Personal access token**. - - -#### Pull Request Provider +#### Specifying Your Pull Request Provider | Parameter Name | Description | | --------------------- | ------------------ | -| `sonar.pullrequest.provider` | `github`, `vsts` or `bitbucketcloud`or `bitbucketserver`. This is the name of the system managing your PR. In Azure DevOps, when the {instance} Extension for Azure DevOps is used, `sonar.pullrequest.provider` is automatically populated with "vsts". Same on GitHub if you are using the Travis CI Add-on, and on Bitbucket Cloud if you are building with Bitbucket Pipelines.| +| `sonar.pullrequest.provider` | `github` or `vsts` or `bitbucketcloud`. This is the name of the system managing your PR. In Azure DevOps, when the {instance} Extension for Azure DevOps is used, `sonar.pullrequest.provider` is automatically populated with "vsts". Same on GitHub if you are using the Travis CI Add-on, and on Bitbucket Cloud if you are building with Bitbucket Pipelines.| + +Note: if you were relying on the GitHub Plugin, its properties are no longer required and they must be removed from your configuration: `sonar.analysis.mode`, `sonar.github.repository`, `sonar.github.pullRequest`, `sonar.github.oauth`. -#### GitHub Parameters + +#### Creating Your GitHub App +To add PR decoration to Checks in GitHub Enterprise, an instance administrator needs to create a GitHub App and configure your SonarQube instance. See [GitHub Enterprise Integration](/instance-administration/github-application/) for more information. + + +#### Setting Your GitHub Parameters | Parameter Name | Description | | --------------------- | ------------------ | | `sonar.pullrequest.github.repository` | SLUG of the GitHub Repo | - -| `sonar.pullrequest.github.endpoint` | The API URL for your GitHub instance.
Ex.: `https://api.github.com/` or `https://github.company.com/api/v3/` | - -Note: if you were relying on the GitHub Plugin, its properties are no longer required and they must be removed from your configuration: `sonar.analysis.mode`, `sonar.github.repository`, `sonar.github.pullRequest`, `sonar.github.oauth`. +#### Setting Your Authentication Token/Personal Access Token + +If you are using Azure DevOps or Bitbucket, you need to configure the authentication token/personal access token that will be used by {instance} to decorate the PRs. This can be configured in **Administration > General Settings > Pull Requests > VSTS > Personal access token**. #### Bitbucket Cloud Parameters diff --git a/server/sonar-docs/src/pages/instance-administration/github-application.md b/server/sonar-docs/src/pages/instance-administration/github-application.md new file mode 100644 index 00000000000..6d3442937cd --- /dev/null +++ b/server/sonar-docs/src/pages/instance-administration/github-application.md @@ -0,0 +1,58 @@ +--- +title: GitHub Enterprise Integration +url: /instance-administration/github-application/ +--- +_GitHub Enterprise Integration is available as part of [Developer Edition](https://redirect.sonarsource.com/editions/developer.html) and [above](https://www.sonarsource.com/plans-and-pricing/)._ + +## Adding Pull Request Decoration to GitHub Checks + +You can add Pull Request decoration to Checks in GitHub Enterprise by creating a GitHub Application, configuring your SonarQube instance, and installing the app in your organizations. + +### Creating a GitHub Application + +Click [here](https://developer.github.com/apps/building-github-apps/creating-a-github-app/) for general instructions on creating a GitHub App. + +From the "Register new GitHub App" page, follow these steps to create your GitHub App for PR decoration: + +1. Under **GitHub App name**, give your app a name (such as SonarQubePRChecks). +2. GitHub requires a **Homepage URL** and a **Webhook URL**. These values aren't important for Pull Request decoration, so you can use any URL (such as https://www.sonarqube.org/). +3. Set the following "Permissions" to **Read & write**: + * Checks + * _Developer Edition v7.2+ Only_: Pull requests (Note: This is only needed to clean up PR decoration in GitHub Conversation. PR decoration in Checks is replacing PR decoration in Conversation.) + * Commit statuses +4. Under "Where can this GitHub App be installed?," select **Any account**. +5. Click **Create GitHub App**. + +### Generating and Setting Your Private Key + +After creating your app, you'll be prompted with a link to "generate a private key" at the top of the page. Click the link to download your .pem private key file. You can also download your .pem file by scrolling down to "Private Key" and clicking **Generate Private Key**. + +After downloading your .pem file, you'll need to set your private key at a global level in SonarQube by following these steps: + +1. Generate a base64 encoded string with your .pem private key file using `base64 -w0 /path/to/key.pem` on Linux or `base64 -i /path/to/key.pem` on MacOS. +2. Copy and paste the base64-encoded content of your private key file into the text box at [**Administration > Pull Requests > GitHub > GitHub App private key**](/#sonarqube-admin#/sonarqube/admin/settings?category=pull_request/). + +### Configuring Your SonarQube Instance + +You'll need to configure the following settings at a global level in SonarQube. + +#### Setting Your GitHub Enterprise Instance API URL + +Enter your GitHub Enterprise Instance API URL in the text box at [**Administration > Pull Requests > GitHub > GitHub API URL**](/#sonarqube-admin#/sonarqube/admin/settings?category=pull_request/). +Your GitHub Enterprise instance API URL is formatted as follows: `https:///api/v3` + +#### Setting Your App Name and ID + +1. Enter your app name in the text box at [**Administration > Pull Requests > GitHub > GitHub App name**](/#sonarqube-admin#/sonarqube/admin/settings?category=pull_request/). +2. Enter your app ID in the text box at [**Administration > Pull Requests > GitHub > GitHub App ID**](/#sonarqube-admin#/sonarqube/admin/settings?category=pull_request/). You can find your GitHub App ID on the app's settings page at `https:///settings/apps/`. + +### Installing Your App + +To install your app in your organizations: + +1. Go to your GitHub App URL. + * GitHub App URLs are specific to your GitHub Enterprise Address and your app name and are formatted as follows: `https:///github-apps/`. + * For example, if your GitHub Enterprise address is `github-enterprise-1.yoursite.com` and your app name is `SonarQubePRChecks`, your GitHub App URL will be `https://github-enterprise-1.yoursite.com/github-apps/SonarQubePRChecks`. +2. From your GitHub App page, click the **Install** or **Configure** button. +3. Choose the organization where you want to install your app from the list. +4. Click the **Install** button. diff --git a/server/sonar-docs/src/pages/requirements/requirements.md b/server/sonar-docs/src/pages/requirements/requirements.md index be217ec4870..78c51616f78 100644 --- a/server/sonar-docs/src/pages/requirements/requirements.md +++ b/server/sonar-docs/src/pages/requirements/requirements.md @@ -80,6 +80,11 @@ To get the full experience SonarQube has to offer, you must enable JavaScript in | Opera | ![](/images/exclamation.svg) Not tested | | Safari | ![](/images/check.svg) Latest | + +## GitHub Enterprise Integration +To add Pull Request analysis to Checks in GitHub Enterprise, you must be running GitHub Enterprise version 2.14+. + + ## Platform notes ### Linux If you're running on Linux, you must ensure that: diff --git a/server/sonar-docs/static/SonarQubeNavigationTree.json b/server/sonar-docs/static/SonarQubeNavigationTree.json index da6a366ef18..3cbedd6cdaf 100644 --- a/server/sonar-docs/static/SonarQubeNavigationTree.json +++ b/server/sonar-docs/static/SonarQubeNavigationTree.json @@ -71,6 +71,7 @@ "/instance-administration/quality-profiles/", "/instance-administration/security/", "/instance-administration/delegated-auth/", + "/instance-administration/github-application/", "/instance-administration/look-and-feel/", "/instance-administration/marketplace/", "/instance-administration/housekeeping/", diff --git a/server/sonar-docs/static/StaticNavigationTree.json b/server/sonar-docs/static/StaticNavigationTree.json index f3cd71b0848..faeca659d80 100644 --- a/server/sonar-docs/static/StaticNavigationTree.json +++ b/server/sonar-docs/static/StaticNavigationTree.json @@ -87,6 +87,7 @@ "/instance-administration/quality-profiles/", "/instance-administration/security/", "/instance-administration/delegated-auth/", + "/instance-administration/github-application/", "/instance-administration/look-and-feel/", "/instance-administration/marketplace/", "/instance-administration/housekeeping/", -- 2.39.5