From f354f42d0d5b53c714c6a51c52e017565db3d37e Mon Sep 17 00:00:00 2001 From: michaelbirnstiehl Date: Mon, 30 Nov 2020 19:09:08 -0600 Subject: [PATCH] DOCS update ALM integration pages --- .../pages/analysis/bitbucket-integration.md | 26 ++++-- .../src/pages/analysis/github-integration.md | 26 +++--- .../src/pages/analysis/gitlab-integration.md | 81 +++++++++++-------- 3 files changed, 78 insertions(+), 55 deletions(-) diff --git a/server/sonar-docs/src/pages/analysis/bitbucket-integration.md b/server/sonar-docs/src/pages/analysis/bitbucket-integration.md index b0a2b1ff91a..b329a70b7b0 100644 --- a/server/sonar-docs/src/pages/analysis/bitbucket-integration.md +++ b/server/sonar-docs/src/pages/analysis/bitbucket-integration.md @@ -4,23 +4,37 @@ url: /analysis/bitbucket-integration/ --- SonarQube's integration with Bitbucket Server allows you to maintain code quality and security in your Bitbucket Server repositories. -Once you've set up your integration, you'll be able to: +With this integration, you'll be able to: - **Import your BitBucket repositories** - (starting in [Developer Edition](https://redirect.sonarsource.com/editions/developer.html)) Import your Bitbucket repositories into SonarQube to easily set up SonarQube projects. -- **Add pull request decoration** - (starting in Developer Edition) See your Quality Gate and code metric results right in Bitbucket so you know if it's safe to merge your changes. +- **Add pull request decoration** - (starting in [Developer Edition](https://redirect.sonarsource.com/editions/developer.html)) See your Quality Gate and code metric results right in Bitbucket so you know if it's safe to merge your changes. ## Prerequisites - Integration with Bitbucket Server requires at least Bitbucket Server version 5.15. ## Importing your Bitbucket Server repositories into SonarQube -Setting up repository import with Bitbucket Server allows you to easily create SonarQube projects from your Bitbucket Server repositories. This is also the first step in adding pull request decoration. +Setting up the import of BitBucket Server repositories into SonarQube allows you to easily create SonarQube projects from your Bitbucket Server repositories. This is also the first step in adding pull request decoration. +To set up the import of BitBucket Server repositories: +1. Set your global settings +1. Add a personal access token for importing repositories + +### Setting your global settings To import your Bitbucket Server projects into SonarQube, you need to first set your global SonarQube settings. Navigate to **Administration > Configuration > General Settings > ALM Integrations**, select the **Bitbucket** tab, and specify the following settings: - **Configuration Name** (Enterprise and Data Center Edition only) – The name used to identify your Bitbucket Server configuration at the project level. Use something succinct and easily recognizable. - **Bitbucket Server URL** – your instances URL. For example, `https://bitbucket-server.your-company.com`. - **Personal Access Token** – A Bitbucket Server user account is used to decorate Pull Requests. We recommend using a dedicated Bitbucket Server account with Administrator permissions. You need a [Personal Access Token](https://confluence.atlassian.com/bitbucketserver0515/personal-access-tokens-961275199.html) from this account with **Write** permission for the repositories that will be analyzed. +### Adding a personal access token for importing repositories +After setting these global settings, you can add a project from Bitbucket Server by clicking the "+" in the upper-right corner and selecting **Bitbucket**: + +![import a Bitbucket project](/images/add-bitbucket-project.png) + +Then, you'll be asked to provide a personal access token from your user account with `Read` permissions for both projects and repositories. This token will be stored in SonarQube and can be revoked at anytime in Bitbucket Server. + +After saving your Personal Access Token, you'll see a list of your Bitbucket Server projects that you can **set up** to add them to SonarQube. Setting up your projects this way also sets your project settings for pull request decoration. + ## Adding pull request decoration to Bitbucket Server Pull request decoration shows your Quality Gate and analysis metrics directly in Bitbucket Server: @@ -29,11 +43,9 @@ Pull request decoration shows your Quality Gate and analysis metrics directly in [[info]] | To decorate 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](/analysis/pull-request/) page. -After you've set up SonarQube to import your Bitbucket Server repositories as shown in the previous section, the simplest way to add pull request decoration is by importing a Bitbucket Server repository: - -![import a Bitbucket project](/images/add-bitbucket-project.png) +After you've set up SonarQube to import your Bitbucket Server repositories as shown in the previous section, the simplest way to add pull request decoration is by adding a project from Bitbucket Server by clicking the "+" in the upper-right corner and selecting **Bitbucket**. -Follow the steps in SonarQube to automatically sets your project settings for pull request decoration. When creating your project, you'll need to provide a personal access token from your user account with `Read` permissions for both projects and repositories. This personal access token will be stored in SonarQube until you revoke it on the Bitbucket Server side. +Then, follow the steps in SonarQube to analyze your project. The project settings for pull request decoration are set automatically. ### Adding pull request decoration to a manually created or existing project To add pull request decoration to a manually created or existing project, after you've created and installed your GitHub App and updated your global ALM Integration settings as shown above, set your project settings at **Project Settings > General Settings > Pull Request Decoration**. diff --git a/server/sonar-docs/src/pages/analysis/github-integration.md b/server/sonar-docs/src/pages/analysis/github-integration.md index 5905fab12c6..b71e9ca2610 100644 --- a/server/sonar-docs/src/pages/analysis/github-integration.md +++ b/server/sonar-docs/src/pages/analysis/github-integration.md @@ -5,14 +5,14 @@ url: /analysis/github-integration/ SonarQube's integration with GitHub Enterprise and GitHub.com allows you to maintain code quality and security in your GitHub repositories. -Once you've set up your integration, you'll be able to: +With this integration, you'll be able to: - **Import your GitHub repositories** - (starting in [Developer Edition](https://redirect.sonarsource.com/editions/developer.html)) Import your GitHub repositories into SonarQube to easily set up SonarQube projects. -- **Add pull request decoration** - (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** - (starting in Community Edition) Sign in to SonarQube with your GitHub credentials. +- **Add pull request decoration** - (starting in [Developer Edition](https://redirect.sonarsource.com/editions/developer.html)) 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. ## Prerequisites -- To add pull request decoration to Checks in GitHub Enterprise, you must be running GitHub Enterprise version 2.15+. +To add pull request decoration to Checks in GitHub Enterprise, you must be running GitHub Enterprise version 2.15+. ## Importing your GitHub repositories to SonarQube You need to use a GitHub App to connect SonarQube and GitHub so you can import your GitHub repositories into SonarQube. This is the first step in setting up pull request decoration and GitHub authentication. @@ -31,10 +31,10 @@ See GitHub's documentation on [creating a GitHub App](https://docs.github.com/ap Specify the following settings in your app: -- **GitHub App Name** – your app's name. -- **Homepage URL** – you can use any URL, such as `https://www.sonarqube.org/`. -- **User authorization callback URL** – your instance's base URL. For example, `https://yourinstance.sonarqube.com`. -- **Webhook URL** – your instance's base URL. For example, `https://yourinstance.sonarqube.com`. +- **GitHub App Name** – Your app's name. +- **Homepage URL** – You can use any URL, such as `https://www.sonarqube.org/`. +- **User authorization callback URL** – Your instance's base URL. For example, `https://yourinstance.sonarqube.com`. +- **Webhook URL** – Your instance's base URL. For example, `https://yourinstance.sonarqube.com`. - Grant access for the following **Repository permissions**: | Permission | Access | @@ -50,7 +50,7 @@ Specify the following settings in your app: | 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 -You need to install your GitHub App in your organizations. 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. +Next, you need to install your GitHub App in your organizations. 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. ### 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. @@ -60,8 +60,8 @@ Navigate to **Administration > Configuration > General Settings > ALM Integratio - **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/v3` for GitHub Enterprise or `https://api.github.com/` for GitHub.com. - **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. +- **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. - **Private Key** – Your GitHub App's private key. You can generate a `.pem` file from your GitHub App's page under **Private keys**. Copy and paste the contents of the file here. ## Adding pull request decoration to GitHub @@ -72,11 +72,11 @@ After creating and installing your GitHub App above, you can add pull request de [[info]] | To decorate 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](/analysis/pull-request/) page. -The simplest way to add pull request decoration is by creating a SonarQube project from your GitHub repository: +The simplest way to add pull request decoration is by adding a project from GitHub by clicking the "+" in the upper-right corner and selecting **GitHub**. ![import a GitHub repository](/images/add-github-project.png) -Follow the steps in the SonarQube UI to automatically set your project settings for pull request decoration. +Then, follow the steps in SonarQube to analyze your project. The project settings for pull request decoration are set automatically. ### Adding pull request decoration to a manually created or existing project To add pull request decoration to a manually created or existing project, after you've created and installed your GitHub App and updated your global ALM Integration settings as shown above, set your project settings at **Project Settings > General Settings > Pull Request Decoration**. diff --git a/server/sonar-docs/src/pages/analysis/gitlab-integration.md b/server/sonar-docs/src/pages/analysis/gitlab-integration.md index 2728f039a7f..54170751fc2 100644 --- a/server/sonar-docs/src/pages/analysis/gitlab-integration.md +++ b/server/sonar-docs/src/pages/analysis/gitlab-integration.md @@ -5,12 +5,12 @@ url: /analysis/gitlab-integration/ SonarQube's integration with GitLab Self-Managed and GitLab.com allows you to maintain code quality and security in your GitLab projects. -Once you've set up your integration, you'll be able to: +With this integration, you'll be able to: - **Authenticate with GitLab** - (starting in Community Edition) Sign in to SonarQube with your GitLab credentials. - **Import your GitLab projects** - (starting in [Developer Edition](https://redirect.sonarsource.com/editions/developer.html)) Import your GitLab Projects into SonarQube to easily set up SonarQube projects. -- **Add merge request decoration** - (starting in Developer Edition) See your Quality Gate and code metric results right in GitLab so you know if it's safe to merge your changes. - **Analyze projects with GitLab CI/CD** - SonarScanners running in GitLab CI/CD jobs can automatically detect branches or merge requests being built so you don't need to specifically pass them as parameters to the scanner. +- **Add merge request decoration** - (starting in [Developer Edition](https://redirect.sonarsource.com/editions/developer.html)) See your Quality Gate and code metric results right in GitLab so you know if it's safe to merge your changes. ## Prerequisites - Integration with GitLab Self-Managed requires at least GitLab Self-Managed version 11.7. @@ -49,49 +49,29 @@ For example, with the following GitLab group setup: You should name your SonarQube group `my-group` to synchronize it with your GitLab group and `my-group/my-subgroup` to synchronize it with your GitLab subgroup. ## Importing your GitLab projects into SonarQube -Setting up project import with GitLab allows you to easily create SonarQube projects from your GitLab projects. This is also the first step in adding merge request decoration. +Setting up the import of GitLab projects into SonarQube allows you to easily create SonarQube projects from your GitLab projects. This is also the first step in adding merge request decoration. +To set up the import of GitLab projects: +1. Set your global settings +1. Add a personal access token for importing repositories + +### Setting your global settings To import your GitLab projects into SonarQube, you need to first set your global SonarQube settings. Navigate to **Administration > Configuration > General Settings > ALM Integrations**, select the **GitLab** tab, and specify the following settings: - **Configuration Name** (Enterprise and Data Center Edition only) – The name used to identify your GitLab configuration at the project level. Use something succinct and easily recognizable. - **GitLab URL** – The GitLab API URL. -- **Personal Access Token** – A GitLab user account is used to decorate Merge Requests. We recommend using a dedicated GitLab account with at least **Reporter** [permissions](https://docs.gitlab.com/ee/user/permissions.html) (the account needs permission to leave comments). You need a personal access token from this account with the scope authorized for **api** for the repositories that will be analyzed. - -## Adding merge request decoration to GitLab - -Merge request decoration shows your Quality Gate and analysis metrics directly in GitLab: - -![pull request decoration](/images/github-branch-decoration.png) +- **Personal Access Token** – A GitLab user account is used to decorate Merge Requests. We recommend using a dedicated GitLab account with at least **Reporter** [permissions](https://docs.gitlab.com/ee/user/permissions.html) (the account needs permission to leave comments). You need a personal access token from this account with the scope authorized for **api** for the repositories that will be analyzed. This -[[info]] -| To decorate merge requests, a SonarQube analysis needs to be run on your code. You can find the additional parameters required for merge request analysis on the [Pull Request Analysis](/analysis/pull-request/) page. - -After you've set up SonarQube to import your GitLab projects as shown in the previous section, the simplest way to add merge request decoration is by importing a project from GitLab: +### Adding a personal access token for importing projects +After setting these global settings, you can add a project from GitLab by clicking the "+" in the upper-right corner and selecting **GitLab**: ![import a GitLab project](/images/add-gitlab-project.png) -Follow the steps in SonarQube to automatically set your project settings for merge request decoration. When creating your project, you'll need to provide a personal access token from your user account with the **read_api** scope. This personal access token will be stored in SonarQube until you revoke it on the GitLab side. +Then, you'll be asked to provide a personal access token with `read_api` scope so SonarQube can access and list your GitLab projects. This token will be stored in SonarQube and can be revoked at anytime in GitLab. -### Adding merge request decoration to a manually created or existing project -To add merge request decoration to a manually created or existing project, after you've set your global ALM Integration settings as shown above, set your project-level settings at **Project Settings > General Settings > Pull Request Decoration**. +After saving your Personal Access Token, you'll see a list of your GitLab projects that you can **set up** to add them to SonarQube. Setting up your projects this way also sets your project settings for merge request decoration. -From here, set your: -- **Configuration name** – The configuration name that corresponds to your GitHub instance. -- **Repository identifier** – The path of your repository URL. - -### Advanced merge request decoration configuration - -[[collapse]] -| ## **Configuring multiple ALM instances** -|You can decorate merge requests from multiple ALM instances by creating a configuration for each ALM instance and then assigning that instance configuration to the appropriate projects. -| -|- As part of [Developer Edition](https://redirect.sonarsource.com/editions/developer.html), you can create one configuration for each ALM. -| -|- Starting in [Enterprise Edition](https://redirect.sonarsource.com/editions/enterprise.html), you can create multiple configurations for each ALM. If you have multiple configurations of the same ALM connected to SonarQube, you have to create projects manually. - -[[collapse]] -| ## **Linking issues** -| During pull request decoration, individual issues will be linked to their SonarQube counterparts automatically. For this to work correctly, you need to set the instance's **Server base URL** (**[Administration > Configuration > General Settings > General > General](/#sonarqube-admin#/admin/settings/)**) correctly. Otherwise, the links will default to `localhost`. +For information on analyzing your projects with GitLab CI/CD, see the following section. ## Analyzing projects with GitLab CI/CD SonarScanners running in GitLab CI/CD jobs can automatically detect branches or merge requests being built so you don't need to specifically pass them as parameters to the scanner. @@ -194,4 +174,35 @@ In order for the Quality Gate to fail on the GitLab side when it fails on the So 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. ### For more information -For more information on configuring your build with GitLab CI/CD, see the [GitLab CI/CD Pipeline Configuration Reference](https://gitlab.com/help/ci/yaml/README.md). \ No newline at end of file +For more information on configuring your build with GitLab CI/CD, see the [GitLab CI/CD Pipeline Configuration Reference](https://gitlab.com/help/ci/yaml/README.md). + +## Adding merge request decoration to GitLab + +Merge request decoration shows your Quality Gate and analysis metrics directly in GitLab: + +![pull request decoration](/images/github-branch-decoration.png) + +After you've set up SonarQube to import your GitLab projects as shown in the previous section, the simplest way to add merge request decoration is by adding a project from GitLab by clicking the "+" in the upper-right corner and selecting **GitLab**. + +Then, follow the steps in SonarQube to analyze your project. The project settings for merge request decoration are set automatically. + +### Adding merge request decoration to a manually created or existing project +To add merge request decoration to a manually created or existing project, after you've set your global ALM Integration settings as shown above, set your project-level settings at **Project Settings > General Settings > Pull Request Decoration**. + +From here, set your: +- **Configuration name** – The configuration name that corresponds to your GitHub instance. +- **Repository identifier** – The path of your repository URL. + +### Advanced merge request decoration configuration + +[[collapse]] +| ## **Configuring multiple ALM instances** +|You can decorate merge requests from multiple ALM instances by creating a configuration for each ALM instance and then assigning that instance configuration to the appropriate projects. +| +|- As part of [Developer Edition](https://redirect.sonarsource.com/editions/developer.html), you can create one configuration for each ALM. +| +|- Starting in [Enterprise Edition](https://redirect.sonarsource.com/editions/enterprise.html), you can create multiple configurations for each ALM. If you have multiple configurations of the same ALM connected to SonarQube, you have to create projects manually. + +[[collapse]] +| ## **Linking issues** +| During pull request decoration, individual issues will be linked to their SonarQube counterparts automatically. For this to work correctly, you need to set the instance's **Server base URL** (**[Administration > Configuration > General Settings > General > General](/#sonarqube-admin#/admin/settings/)**) correctly. Otherwise, the links will default to `localhost`. \ No newline at end of file -- 2.39.5