Connect GitHub PR to SonarQube analysis

This guide aims to cover how to connect a GitHub pull request with a SonarQube analysis to understand the scan results of your PR.

Prerequisites

This guide assumes you have a Port account and that you have finished the onboarding process.
Ensure you have SonarQube ocean integration installed and configured in your environment.
Ensure you have a registered organization in Port and your Port user role is set to Admin.
You will need an accessible k8s cluster. If you don't have one, here is how to quickly set-up a minikube cluster.
Helm - required to install a relevant integration.

Integrate GitHub resources with Port

The goal of this section is to fill the software catalog with data directly from your GitHub organization. Port's GitHub app allows you to import repositories, pull requests, workflows, teams and other GitHub objects. For the purpose of this guide, we shall focus on pull requests (PR) object only. Follow the steps below to ingest your PR data to Port.

Note

For the GitHub app installation you will need to have a registered organization in Port and your Port user role must be set to Admin (see prerequisites).

Go to your Builder

Create a GitHub pull request blueprint using this schema:

GitHub pull request blueprint (click to expand)

{
    "identifier": "githubPullRequest",
    "title": "Pull Request",
    "icon": "Github",
    "schema": {
        "properties": {
        "creator": {
            "title": "Creator",
            "type": "string"
        },
        "assignees": {
            "title": "Assignees",
            "type": "array"
        },
        "reviewers": {
            "title": "Reviewers",
            "type": "array"
        },
        "status": {
            "title": "Status",
            "type": "string",
            "enum": [
            "merged",
            "open",
            "closed"
            ],
            "enumColors": {
            "merged": "purple",
            "open": "green",
            "closed": "red"
            }
        },
        "closedAt": {
            "title": "Closed At",
            "type": "string",
            "format": "date-time"
        },
        "updatedAt": {
            "title": "Updated At",
            "type": "string",
            "format": "date-time"
        },
        "mergedAt": {
            "title": "Merged At",
            "type": "string",
            "format": "date-time"
        },
        "link": {
            "type": "string",
            "format": "url"
        }
        },
        "required": []
    },
    "mirrorProperties": {},
    "calculationProperties": {},
    "aggregationProperties": {},
    "relations": {}
    }

Install Port's GitHub app by following the installation guide

Now that the integration is installed successfully, we need to ingest githubPullRequest data from the GitHub organization into the software catalog. This can be done by adding some mapping logic. Go to your data sources page, and click on your GitHub integration:

Add the following YAML block into the editor to ingest pull request data. Then click Save & Resync:

Relation mapping (click to expand)

resources:
  - kind: pull-request
    selector:
        query: "true"
    port:
        entity:
        mappings:
            identifier: ".head.repo.name + '-' + (.number|tostring)" # The Entity identifier will be the repository name + the pull request number
            title: ".title"
            blueprint: '"githubPullRequest"'
            properties:
                creator: ".user.login"
                assignees: "[.assignees[].login]"
                reviewers: "[.requested_reviewers[].login]"
                status: ".status"
                closedAt: ".closed_at"
                updatedAt: ".updated_at"
                mergedAt: ".merged_at"
                prNumber: ".id"
                link: ".html_url"

You should now be able to see your GitHub pull requests ingested successfully in the software catalog.

Integrate SonarQube into Port

The goal of this section is to bring our SonarQube analysis data into Port. Port's SonarQube integration (powered by Ocean) allows you to import projects, issues and analyses from your SonarQube account into Port. The integration automatically creates blueprints and entities for these resources.

Note

For this installation you will need Helm and a running K8s cluster (see prerequisites).

Install Port's SonarQube integration using Helm, by running the command below in your terminal.

Replace CLIENT_ID and CLIENT_SECRET with your credentials (get them here).
Replace sonarApiToken with your SonarQube token. To obtain it, follow this documentation.
Replace sonarOrganizationId with your SonarQube organization ID. To obtain it, follow this documentation. Note that the SonarQube organization ID is not required when using on-prem sonarqube instance.

Installation command (click to expand)

helm repo add --force-update port-labs https://port-labs.github.io/helm-charts
helm upgrade --install my-sonarqube-integration port-labs/port-ocean \
	--set port.clientId="PORT_CLIENT_ID"  \  # REPLACE VALUE
	--set port.clientSecret="PORT_CLIENT_SECRET"  \  # REPLACE VALUE
	--set initializePortResources=true  \
	--set integration.identifier="my-sonarqube-integration"  \
	--set integration.type="sonarqube"  \
	--set integration.eventListener.type="POLLING"  \
	--set integration.secrets.sonarApiToken="MY_API_TOKEN"  \  # REPLACE VALUE
	--set integration.config.sonarOrganizationId="MY_ORG_KEY"  # REPLACE VALUE

Great! Now that the integration is installed, we should see some new components in Port:
- Go to your Builder, you should now see three new blueprints created by the integration - SonarQube Project, SonarQube Issue and SonarQube Analysis.
- Go to your Software catalog, click on SonarQube Analysis in the sidebar, you should now see new entities created for all your SonarQube analysis.

Create the Sonar analysis relation

Now that Port is synced with our SonarQube resources, let's map the SonarQube analysis to the pull requests to display the result of the sonar scan. First, we will need to create a relation between our githubPullRequest and the corresponding sonarQubeAnalysis.

Head back to the Builder, choose the Pull Request blueprint, and click on New relation:

Fill out the form like this, then click Create:

Now that the blueprints are related, we need to assign the relevant SonarQube analysis to each of our pull requests. This can be done by adding some mapping logic. Go to your data sources page, and click on your GitHub Pull Request integration:

Relation Mapping

There are two ways to establish the relationship between a GitHub pull-request entity and a SonarQube analysis entity:

Matching Common Pull Request Title and Branch

The first way is to use the title and branch properties:

Why use title and branch properties? The title property is common to both GitHub pull requests and SonarQube analyses, making it a reliable identifier for matching related entities. The branch property gives information about the source and destination of the the code changes. Combining the title with the branch offers a robust mapping, ensuring that entities are correctly matched in situations where there are similar pull request titles but on different branches.
Go to your data sources page and click on the GitHub exporter:

Replace the mapping YAML with this content:

resources:
   - kind: pull-request
     selector:
        query: 'true'
     port:
        entity:
           mappings:
              identifier: .head.repo.name + '-' + (.number|tostring)
              title: .title
              blueprint: '"githubPullRequest"'
              properties:
                 creator: .user.login
                 assignees: '[.assignees[].login]'
                 reviewers: '[.requested_reviewers[].login]'
                 status: .status
                 closedAt: .closed_at
                 updatedAt: .updated_at
                 mergedAt: .merged_at
                 prNumber: .id
                 link: .html_url
              relations:
                 sonarAnalysis:
                    combinator: '"and"'
                    rules:
                       - property: '"$title"'
                         operator: '"="'
                         value: .title
                       - property: '"branch"'
                         operator: '"="'
                         value: .head.ref

This configuration uses the title and branch properties to establish a relationship with SonarQube analysis based on matching properties.

Matching Pull Request Commit SHA

The second way is to use the commitSha property that is common to both the pull request and SonarQube analysis:

Go to the data model page of your portal
Go to the SonarQube blueprint.
Hover over it, click on the ... button on the right, and select Edit JSON.

Add the commitSha property and Save:

Go to your data sources page and click on the GitHub exporter:
Replace the pull-request mapping YAML with this content:

  resources:
     - kind: pull-request
       selector:
          query: 'true'
       port:
          entity:
             mappings:
                identifier: .head.repo.name + '-' + (.number|tostring)
                title: .title
                blueprint: '"githubPullRequest"'
                properties:
                   creator: .user.login
                   assignees: '[.assignees[].login]'
                   reviewers: '[.requested_reviewers[].login]'
                   status: .status
                   closedAt: .closed_at
                   updatedAt: .updated_at
                   mergedAt: .merged_at
                   prNumber: .id
                   link: .html_url
                relations:
                   sonarAnalysis:
                      combinator: '"and"'
                      rules:
                         - property: '"commitSha"'
                           operator: '"="'
                           value: .head.sha

Mapping explanation

In this implementation, we used search relation features to map relationships between githubPullRequest entities and sonarAnalysis entities based on specific properties rather than direct identifiers. By using properties like title, branch, and commitSha, we are able to establish a between the two entities.

Configure mirror properties on pull request

When looking at a Pull Request, some of its sonarAnalysis properties may be especially important to us, and we would like to see them directly in the Pull Request's context. This can be achieved using mirror properties, so let's create some:

The first one will be the number of new issues added to the analysis. Under the relation we just created, click on New mirror property:

Fill the form out like this, then click Create:

The second one will be the analysis code duplication. Create another mirror property, fill the form out like this, then click Create:

The third one will be the analysis coverage. Create another mirror property, fill the form out like this, then click Create:

The third one will be the quality gate status of the analysis. Create another mirror property, fill the form out like this, then click Create:

You should now be able to see these additional properties added to pull request entity in your software catalog.

Conclusion

By following these steps, you can seamlessly connect a GitHub pull request with a SonarQube analysis.

More relevant guides and examples:

Integrate GitHub resources with Port​

Integrate SonarQube into Port​

Create the Sonar analysis relation​

Relation Mapping​

Matching Common Pull Request Title and Branch​

Matching Pull Request Commit SHA​

Configure mirror properties on pull request​

Conclusion​