scout: add sonarqube integration

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

content/scout/integrations/_index.md

@@ -52,3 +52,19 @@ versions, in your image repositories or in your other environments.
 
 For more information about environment integrations, see
 [Environments](./environment/index.md).
+
+### Code quality
+
+Integrating Docker Scout with code analysis tools enables quality checks
+directly on source code, helping you keep track of bugs, security issues, test
+coverage, and more. In addition to image analysis and environment monitoring,
+code quality gates let you shift left your supply chain management with Docker
+Scout.
+
+Once you enable a code quality integration, Docker Scout includes the code
+quality assessments as policy evaluation results for the repositories where
+you've enabled the integration.
+
+The following code quality integrations are available:
+
+- [SonarQube](sonarqube.md)

content/scout/integrations/code-quality/sonarqube.md

@@ -0,0 +1,75 @@
+---
+title: Integrate Docker Scout with SonarQube
+description: Evaluate your images with the SonarQube quality gates defined in your projects
+keywords: scout, supply chain, integration, code quality
+---
+
+The SonarQube integration enables Docker Scout to surface SonarQube quality
+gate checks through Policy Evaluation, under a new [Quality gates passed
+policy](../../policy/_index.md#quality-gates-passed).
+
+## How it works
+
+This integration uses [SonarQube
+webhooks](https://docs.sonarsource.com/sonarqube/latest/project-administration/webhooks/)
+to notify Docker Scout of when a SonarQube project analysis has completed. When
+the webhook is called, Docker Scout receives the analysis results, and stores
+them in the database.
+
+When you push a new image to a repository, Docker Scout evaluates the results
+of the SonarQube analysis record corresponding to the image. Docker Scout uses
+Git provenance metadata on the images, from  provenance attestations or an OCI
+annotations, to link image repositories with SonarQube analysis results.
+
+> **Note**
+>
+> Docker Scout doesn't have access to historic SonarQube analysis records. Only
+> analysis results recorded after the integration is enabled will be available
+> to Docker Scout.
+
+## Prerequisites
+
+To integrate Docker Scout with SonarQube, ensure that:
+
+- Your image repository is [integrated with Docker Scout](../_index.md#container-registries).
+- Your images are built with [provenance attestations](../../../build/attestations/slsa-provenance.md),
+  or the `org.opencontainers.image.revision` annotation,
+  containing information about the Git repository.
+
+## Enable the SonarQube integration
+
+1. Go to [Integrations](https://scout.docker.com/settings/integrations/) on the
+   Docker Scout Dashboard.
+2. Select the **See all integration options** filter.
+3. Find the SonarQube integration in the **Code quality** section, and
+   select **Integrate**.
+4. In the **How to integrate** section, enter a configuration name for this
+   integration. Docker Scout uses this label as a display name for the
+   integration, and to name the webhook.
+5. Select **Next**.
+6. Enter the configuration details for your SonarQube instance. Docker Scout
+   uses this information to create SonarQube webhook.
+
+   In SonarQube, [generate a new **User
+   token**](https://docs.sonarsource.com/sonarqube/9.8/user-guide/user-account/generating-and-using-tokens/#generating-a-token).
+   The token requires 'Administer' permission on the specified project, or
+   global 'Administer' permission.
+
+   Enter the token, your SonarQube URL, and the ID of your SonarQube
+   organization. The SonarQube organization is required if you're using
+   SonarCloud.
+
+7. Select **Enable configuration**.
+
+   Docker Scout performs a connection test to verify that the provided details
+   are correct, and that the token has the necessary permissions.
+
+8. After a successful connection test, you're redirected to the SonarQube
+   integration overview, which lists all your SonarQube integrations and their
+   statuses.
+
+From the integration overview page, you can go directly to the Quality gates
+passed policy. This policy will have no results initially. To start seeing
+evaluation results for this policy, trigger a new SonarQube analysis of your
+project and push the corresponding image to a repository. For more information,
+refer to the [Quality gates passed policy](../../policy/_index.md#quality-gates-passed).

content/scout/policy/_index.md

@@ -60,6 +60,7 @@ Docker Scout ships the following out-of-the-box policies:
 - [Outdated base images](#outdated-base-images)
 - [High-profile vulnerabilities](#high-profile-vulnerabilities)
 - [Supply chain attestations](#supply-chain-attestations)
+- [Quality gates passed](#quality-gates-passed)
 
 Policies are enabled by default for Scout-enabled repositories. If you want to
 customize the criteria of a policy, you can create custom policies based on the
@@ -181,3 +182,35 @@ building with attestations, see
 > Docker Scout is currently unable to discern the difference between using
 > `scratch` as a base image and having no base image provenance. As a result,
 > images based on `scratch` always fail the Supply chain attestations policy.
+
+### Quality gates passed
+
+The Quality gates passed policy builds on the [SonarQube
+integration](../integrations/code-quality/sonarqube.md) to assess the quality
+of your source code. This policy works by ingesting the SonarQube code analysis
+results into Docker Scout.
+
+You define the criteria for this policy using SonarQube's [quality
+gates](https://docs.sonarsource.com/sonarqube/latest/user-guide/quality-gates/).
+SonarQube evaluates your source code against the quality gates you've defined
+in SonarQube. Docker Scout surfaces the SonarQube assessment as a Docker Scout
+policy.
+
+Docker Scout uses [provenance](../../build/attestations/slsa-provenance.md)
+attestations or the `org.opencontainers.image.revision` OCI annotation to link
+SonarQube analysis results with container images. In addition to enabling the
+SonarQube integration, you must also make sure that your images has either the
+attestation or the label.
+
+![Git commit SHA links image with SonarQube analysis](../images/scout-sq-commit-sha.webp)
+
+Once you push an image and policy evaluation completes, the results from the
+SonarQube quality gates display as a policy in the Docker Scout Dashboard, and
+in the CLI.
+
+> **Note**
+>
+> Docker Scout can only access SonarQube analyses created after the integration
+> is enabled. Docker Scout doesn't have access to historic evaluations. Trigger
+> a SonarQube analysis and policy evaluation after enabling the integration to
+> view the results in Docker Scout.

data/redirects.yml

@@ -607,6 +607,8 @@
   - "/go/scout-sysdig/"
 "/scout/integrations/registry/acr/":
   - "/go/scout-acr/"
+"/scout/integrations/code-quality/sonarqube/":
+  - "/go/scout-sq/"
 
 # Build links
 "/desktop/use-desktop/builds/":

data/toc.yaml

@@ -1407,6 +1407,10 @@ Manuals:
           path: /scout/integrations/ci/circle-ci/
         - title: Jenkins
           path: /scout/integrations/ci/jenkins/
+      - sectiontitle: Code quality
+        section:
+        - title: SonarQube
+          path: /scout/integrations/code-quality/sonarqube/
     - path: /scout/release-notes/
       title: Release notes