Skip to main content

SonarQube

Port's SonarQube integration (powered by Ocean) allows you to import projects, issues and analyses from your SonarQube account into Port, according to your mapping and definitions.

Common use cases​

  • Map projects, issues, analyses and portfolios in your SonarQube organization environment.
  • Watch for object changes (create/update/delete) in real-time, and automatically apply the changes to your entities in Port.
  • Create/delete SonarQube objects using self-service actions.

Prerequisites​

To install the integration, you need a Kubernetes cluster that the integration's container chart will be deployed to.

Please make sure that you have kubectl and helm installed on your machine, and that your kubectl CLI is connected to the Kubernetes cluster where you plan to install the integration.

Troubleshooting

If you are having trouble installing this integration, please refer to these troubleshooting steps.

Installation​

Choose one of the following installation methods:

Using this installation option means that the integration will be hosted by Port, with a customizable resync interval to ingest data into Port.

Beta feature

The Hosted by Port option is currently in beta, and is still undergoing final testing before its official release.

Should you encounter any bugs or functionality issues, please let us know so we can rectify them as soon as possible.
Your help is greatly appreciated! ⭐

Live event support

Currently, live events are not supported for integrations hosted by Port.
Resyncs will be performed periodically every 1 hour by default (can be configured differently after installation), or manually triggered by you via Port's UI.

Therefore, real-time events (including GitOps) will not be ingested into Port immediately.
Support for live events is WIP and will be supported in the near future.

Installation

To install, follow the following steps:

  1. Go to the Data sources page of your portal.

  2. Click on the + Data source button in the top-right corner.

  3. Click on the relevant integration in the list.

  4. Under Select your installation method, choose Hosted by Port.

  5. Configure the integration settings and application settings as you wish (see below for details).

Application settings

Every integration hosted by Port has the following customizable application settings, which are configurable after installation:

  • Resync interval: The frequency at which Port will ingest data from the integration. There are various options available, ranging from every 1 hour to once a day.

  • Send raw data examples: A boolean toggle (enabled by default). If enabled, raw data examples will be sent from the integration to Port. These examples are used when testing your mapping configuration, they allow you to run your jq expressions against real data and see the results.

Integration settings

Every integration has its own tool-specific settings, under the Integration settings section.
Each of these settings has an ⓘ icon next to it, which you can hover over to see a description of the setting.

Port secrets

Some integration settings require sensitive pieces of data, such as tokens.
For these settings, Port secrets will be used, ensuring that your sensitive data is encrypted and secure.

When changing such a setting, you will be prompted to choose an existing secret or create a new one:



Port source IP addresses

When using this installation method, Port will make outbound calls to your 3rd-party applications from static IP addresses.
You may need to add these addresses to your allowlist, in order to allow Port to interact with the integrated service:

54.73.167.226  
63.33.143.237  
54.76.185.219

Ingesting SonarQube objects​

The SonarQube integration uses a YAML configuration to describe the process of loading data into the developer portal.

Here is an example snippet from the config which demonstrates the process for getting project data from SonarQube:

resources:
  - kind: projects
    selector:
      query: "true"
    port:
      entity:
        mappings:
          blueprint: '"sonarQubeProject"'
          identifier: .key
          title: .name
          properties:
            organization: .organization
            link: .__link
            lastAnalysisStatus: .__branch.status.qualityGateStatus
            lastAnalysisDate: .__branch.analysisDate
            numberOfBugs: .__measures[]? | select(.metric == "bugs") | .value
            numberOfCodeSmells: .__measures[]? | select(.metric == "code_smells") | .value
            numberOfVulnerabilities: .__measures[]? | select(.metric == "vulnerabilities") | .value
            numberOfHotSpots: .__measures[]? | select(.metric == "security_hotspots") | .value
            numberOfDuplications: .__measures[]? | select(.metric == "duplicated_files") | .value
            coverage: .__measures[]? | select(.metric == "coverage") | .value
            mainBranch: .__branch.name
            tags: .tags

The integration makes use of the JQ JSON processor to select, modify, concatenate, transform and perform other operations on existing fields and values from SonarQube's API events.

Configuration structure​

The integration configuration determines which resources will be queried from SonarQube, and which entities and properties will be created in Port.

Supported resources

The following resources can be used to map data from SonarQube, it is possible to reference any field that appears in the API responses linked below for the mapping configuration.

  • Project - represents a SonarQube project. Retrieves data from components, measures, and branches.
  • Issue - represents a SonarQube issue
  • Saas Analysis - represents analysis and latest activity in your SonarCloud environment.
  • On-premise Analysis - since SonarQube doesn't offer a straightforward API for fetching analysis and latest activity in on-premise installations, our integration provides an alternative solution for on-premise installation. By utilizing the pull requests and measures APIs, users can now visualize the results of scan analyses for each pull request.
  • The root key of the integration configuration is the resources key:
resources:
  - kind: ONE_OF_THE_SUPPORTED_KINDS
    selector:
    ...
  • The kind key is a specifier for a SonarQube object:
  resources:
    - kind: ONE_OF_THE_SUPPORTED_KINDS
      selector:
      ...
  • The selector and the query keys allow you to filter which objects of the specified kind will be ingested into your software catalog:
resources:
  - kind: { props.customKind }
    selector:
      query: "true" # JQ boolean expression. If evaluated to false - this object will be skipped.
    port:
  • The port, entity and the mappings keys are used to map the SonarQube object fields to Port entities. To create multiple mappings of the same kind, you can add another item in the resources array;
resources:
  - kind: projects
    selector:
      query: "true"
    port:
      entity:
        mappings:
          blueprint: '"sonarQubeProject"'
          identifier: .key
          title: .name
          properties:
            organization: .organization
            link: .__link
            lastAnalysisStatus: .__branch.status.qualityGateStatus
            lastAnalysisDate: .__branch.analysisDate
            numberOfBugs: .__measures[]? | select(.metric == "bugs") | .value
            numberOfCodeSmells: .__measures[]? | select(.metric == "code_smells") | .value
            numberOfVulnerabilities: .__measures[]? | select(.metric == "vulnerabilities") | .value
            numberOfHotSpots: .__measures[]? | select(.metric == "security_hotspots") | .value
            numberOfDuplications: .__measures[]? | select(.metric == "duplicated_files") | .value
            coverage: .__measures[]? | select(.metric == "coverage") | .value
            mainBranch: .__branch.name
            tags: .tags
  - kind: projects # In this instance project is mapped again with a different filter
    selector:
      query: '.name == "MyProjectName"'
    port:
      entity:
        mappings: ...
Blueprint key

Note the value of the blueprint key - if you want to use a hardcoded string, you need to encapsulate it in 2 sets of quotes, for example use a pair of single-quotes (') and then another pair of double-quotes (")

Ingest data into Port​

To ingest SonarQube objects using the integration configuration, you can follow the steps below:

  1. Go to the DevPortal Builder page.
  2. Select a blueprint you want to ingest using SonarQube.
  3. Choose the Ingest Data option from the menu.
  4. Select SonarQube under the Code quality & security providers category.
  5. Modify the configuration according to your needs.
  6. Click Resync.

Examples​

Examples of blueprints and the relevant integration configurations:

Project​

Projects blueprint (Click to expand)
{
  "identifier": "sonarQubeProject",
  "title": "SonarQube Project",
  "icon": "sonarqube",
  "schema": {
    "properties": {
      "organization": {
        "type": "string",
        "title": "Organization",
        "icon": "TwoUsers"
      },
      "link": {
        "type": "string",
        "format": "url",
        "title": "Link",
        "icon": "Link"
      },
      "lastAnalysisDate": {
        "type": "string",
        "format": "date-time",
        "icon": "Clock",
        "title": "Last Analysis Date"
      },
      "numberOfBugs": {
        "type": "number",
        "title": "Number Of Bugs"
      },
      "numberOfCodeSmells": {
        "type": "number",
        "title": "Number Of CodeSmells"
      },
      "numberOfVulnerabilities": {
        "type": "number",
        "title": "Number Of Vulnerabilities"
      },
      "numberOfHotSpots": {
        "type": "number",
        "title": "Number Of HotSpots"
      },
      "numberOfDuplications": {
        "type": "number",
        "title": "Number Of Duplications"
      },
      "coverage": {
        "type": "number",
        "title": "Coverage"
      },
      "mainBranch": {
        "type": "string",
        "icon": "Git",
        "title": "Main Branch"
      },
      "tags": {
        "type": "array",
        "title": "Tags"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "relations": {}
}
Integration configuration (Click to expand)
filter projects

The integration provides an option to filter the data that is retrieved from the SonarQube API using the following attributes:

  1. query: Limits the search to component names that contain the supplied string
  2. alertStatus: To filter a project's quality gate status. Accepts a list of values such as OK, ERROR and WARN
  3. languages: To filter projects using a list of languages or a single language
  4. tags: To filter a list of tags or a single tag
  5. qualifier: To filter on a component qualifier. Accepts values such as TRK (for projects only) and APP (for applications only)

These attributes can be enabled using the path: selector.apiFilters.filter. By default, the integration fetches only SonarQube projects using the qualifier attribute.

Define your own metrics

Besides filtering the API data, the integration provides a mechanism to allow users to define their own list of metrics used in SonarQube to evaluate the code. This list can be defined in the selector.metrics property. A complete list of valid SonarQube metrics can be in the SonarQube documentation

Supported Sonar environment

Please note that the API filters are supported on on-premise Sonar environments (SonarQube) only, and will not work on SonarCloud.

createMissingRelatedEntities: true
deleteDependentEntities: true
resources:
  - kind: projects
    selector:
      query: "true"
      apiFilters:
        filter:
          qualifier: TRK
      metrics:
        - code_smells
        - coverage
        - bugs
        - vulnerabilities
        - duplicated_files
        - security_hotspots
        - new_violations
        - new_coverage
        - new_duplicated_lines_density
    port:
      entity:
        mappings:
          blueprint: '"sonarQubeProject"'
          identifier: .key
          title: .name
          properties:
            organization: .organization
            link: .__link
            lastAnalysisStatus: .__branch.status.qualityGateStatus
            lastAnalysisDate: .__branch.analysisDate
            numberOfBugs: .__measures[]? | select(.metric == "bugs") | .value
            numberOfCodeSmells: .__measures[]? | select(.metric == "code_smells") | .value
            numberOfVulnerabilities: .__measures[]? | select(.metric == "vulnerabilities") | .value
            numberOfHotSpots: .__measures[]? | select(.metric == "security_hotspots") | .value
            numberOfDuplications: .__measures[]? | select(.metric == "duplicated_files") | .value
            coverage: .__measures[]? | select(.metric == "coverage") | .value
            mainBranch: .__branch.name
            tags: .tags

Issue​

Issue blueprint (Click to expand)
{
  "identifier": "sonarQubeIssue",
  "title": "SonarQube Issue",
  "icon": "sonarqube",
  "schema": {
    "properties": {
      "type": {
        "type": "string",
        "title": "Type",
        "enum": ["CODE_SMELL", "BUG", "VULNERABILITY"]
      },
      "severity": {
        "type": "string",
        "title": "Severity",
        "enum": ["MAJOR", "INFO", "MINOR", "CRITICAL", "BLOCKER"],
        "enumColors": {
          "MAJOR": "orange",
          "INFO": "green",
          "CRITICAL": "red",
          "BLOCKER": "red",
          "MINOR": "yellow"
        }
      },
      "link": {
        "type": "string",
        "format": "url",
        "icon": "Link",
        "title": "Link"
      },
      "status": {
        "type": "string",
        "title": "Status",
        "enum": ["OPEN", "CLOSED", "RESOLVED", "REOPENED", "CONFIRMED"]
      },
      "assignees": {
        "title": "Assignees",
        "type": "string",
        "icon": "TwoUsers"
      },
      "tags": {
        "type": "array",
        "title": "Tags"
      },
      "createdAt": {
        "type": "string",
        "format": "date-time",
        "title": "Created At"
      }
    }
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "relations": {
    "sonarQubeProject": {
      "target": "sonarQubeProject",
      "required": false,
      "title": "SonarQube Project",
      "many": false
    }
  }
}
Integration configuration (Click to expand)
filter issues

The integration provides an option to filter the data that is retrieved from the SonarQube API using the following attributes:

  1. assigned: To retrieve assigned or unassigned issues. Accepts values: yes, no, true, false
  2. assignees: A list of assignee logins
  3. cleanCodeAttributeCategories: List of clean code attribute categories. Accepts values: ADAPTABLE, CONSISTENT, INTENTIONAL, RESPONSIBLE
  4. createdBefore: To retrieve issues created before the given date
  5. createdAfter: To retrieve issues created after the given date
  6. impactSeverities: List of impact severities. Accepts values: HIGH, LOW, MEDIUM
  7. impactSoftwareQualities: List of impact software qualities. Accepts values: MAINTAINABILITY, RELIABILITY, SECURITY
  8. statuses: List of statuses. Accepts values: OPEN, CONFIRMED, FALSE_POSITIVE, ACCEPTED, FIXED
  9. languages: List of languages
  10. resolved: To retrieve resolved or unresolved issues. Accepts values: yes, no, true, false
  11. scopes: List of scopes. Accepts values: MAIN, TESTS
  12. tags: List of tags

These attributes can be enabled using the path: selector.apiFilters. By default, the integration fetches unresolved SonarQube issues. It is also possible to configure the integration to fetch issues from a SonarQube project using the path: selector.projectApiFilters.filter while specifying any of the above project attributes

Supported Sonar environment

Please note that the API filters are supported on on-premise Sonar environments (SonarQube) only, and will not work on SonarCloud.

createMissingRelatedEntities: true
deleteDependentEntities: true
resources:
  - kind: issues
    selector:
      query: "true"
      apiFilters:
        resolved: 'false'
      projectApiFilters:
        filter:
          qualifier: TRK
    port:
      entity:
        mappings:
          blueprint: '"sonarQubeIssue"'
          identifier: .key
          title: .message
          properties:
            type: .type
            severity: .severity
            link: .__link
            status: .status
            assignees: .assignee
            tags: .tags
            createdAt: .creationDate
          relations:
            sonarQubeProject: .project

Saas Analysis​

Saas analysis blueprint (Click to expand)
{
  "identifier": "sonarQubeAnalysis",
  "title": "SonarQube Analysis",
  "icon": "sonarqube",
  "schema": {
    "properties": {
      "branch": {
        "type": "string",
        "title": "Branch",
        "icon": "GitVersion"
      },
      "fixedIssues": {
        "type": "number",
        "title": "Fixed Issues"
      },
      "newIssues": {
        "type": "number",
        "title": "New Issues"
      },
      "coverage": {
        "title": "Coverage",
        "type": "number"
      },
      "duplications": {
        "type": "number",
        "title": "Duplications"
      },
      "createdAt": {
        "type": "string",
        "format": "date-time",
        "title": "Created At"
      }
    }
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "relations": {
    "sonarQubeProject": {
      "target": "sonarQubeProject",
      "required": false,
      "title": "SonarQube Project",
      "many": false
    }
  }
}
Integration configuration (Click to expand)
createMissingRelatedEntities: true
deleteDependentEntities: true
resources:
  - kind: saas_analysis
    selector:
      query: "true"
    port:
      entity:
        mappings:
          blueprint: '"sonarQubeAnalysis"'
          identifier: .analysisId
          title: .__commit.message // .analysisId
          properties:
            branch: .__branchName
            fixedIssues: .measures.violations_fixed
            newIssues: .measures.violations_added
            coverage: .measures.coverage_change
            duplications: .measures.duplicated_lines_density_change
            createdAt: .__analysisDate
          relations:
            sonarQubeProject: .__project

On-Premise Analysis​

On-premise analysis blueprint (Click to expand)
{
  "identifier": "sonarQubeAnalysis",
  "title": "SonarQube Analysis",
  "icon": "sonarqube",
  "schema": {
    "properties": {
      "branch": {
        "type": "string",
        "title": "Branch",
        "icon": "GitVersion"
      },
      "fixedIssues": {
        "type": "number",
        "title": "Fixed Issues"
      },
      "newIssues": {
        "type": "number",
        "title": "New Issues"
      },
      "coverage": {
        "title": "Coverage",
        "type": "number"
      },
      "duplications": {
        "type": "number",
        "title": "Duplications"
      },
      "createdAt": {
        "type": "string",
        "format": "date-time",
        "title": "Created At"
      }
    }
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "relations": {
    "sonarQubeProject": {
      "target": "sonarQubeProject",
      "required": false,
      "title": "SonarQube Project",
      "many": false
    }
  }
}
Integration configuration (Click to expand)
createMissingRelatedEntities: true
deleteDependentEntities: true
resources:
  - kind: onprem_analysis
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          blueprint: '"sonarQubeAnalysis"'
          identifier: .__project + "-" + .key
          title: .title
          properties:
            branch: .branch
            newIssues: .__measures[]? | select(.metric == "new_violations") | .period.value
            coverage: .__measures[]? | select(.metric == "new_coverage") | .period.value
            duplications: .__measures[]? | select(.metric == "new_duplicated_lines_density") | .period.value
            createdAt: .analysisDate
          relations:
            sonarQubeProject: .__project

Portfolio​

Portfolio blueprint (Click to expand)
{
  "identifier": "sonarQubePortfolio",
  "title": "SonarQube Portfolio",
  "icon": "sonarqube",
  "schema": {
    "properties": {
      "description": {
        "type": "string",
        "title": "Description"
      },
      "visibility": {
        "type": "string",
        "title": "Visibility",
        "enum": [
          "PUBLIC",
          "PRIVATE"
        ],
        "enumColors": {
          "PUBLIC": "green",
          "PRIVATE": "lightGray"
        }
      },
      "selectionMode": {
        "type": "string",
        "title": "Selection Mode",
        "enum": [
          "AUTO",
          "MANUAL",
          "NONE"
        ],
        "enumColors": {
          "AUTO": "blue",
          "MANUAL": "green",
          "NONE": "lightGray"
        }
      },
      "disabled": {
        "type": "boolean",
        "title": "Disabled"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "aggregationProperties": {},
  "relations": {
    "referencedBy": {
      "title": "Referenced By",
      "target": "sonarQubePortfolio",
      "required": false,
      "many": true
    },
    "subPortfolios": {
      "title": "Sub Portfolios",
      "target": "sonarQubePortfolio",
      "required": false,
      "many": true
    }
  }
}
Integration configuration (Click to expand)
deleteDependentEntities: true
createMissingRelatedEntities: true
resources:
  - kind: portfolios
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          identifier: .key
          title: .name
          blueprint: '"sonarQubePortfolio"'
          properties:
            description: .description
            visibility: if .visibility then .visibility | ascii_upcase else null end
            selectionMode: if .selectionMode then .selectionMode | ascii_upcase else null end
            disabled: .disabled
          relations:
            subPortfolios: .subViews | map(select((.qualifier | IN("VW", "SVW"))) | .key)
            referencedBy: .referencedBy | map(select((.qualifier | IN("VW", "SVW"))) | .key)

Let's Test It​

This section includes a sample response data from SonarQube when a code repository is scanned for quality assurance. In addition, it includes the entity created from the resync event based on the Ocean configuration provided in the previous section.

Payload​

Here is an example of the payload structure from SonarQube:

Project response data (Click to expand)
{
  "organization": "peygis",
  "key": "PeyGis_Chatbot_For_Social_Media_Transaction",
  "name": "Chatbot_For_Social_Media_Transaction",
  "isFavorite": true,
  "tags": [],
  "visibility": "public",
  "eligibilityStatus": "COMPLETED",
  "eligible": true,
  "isNew": false,
  "analysisDateAllBranches": "2023-09-09T03:03:20+0200",
  "__measures": [
    {
      "metric": "bugs",
      "value": "6",
      "bestValue": false
    },
    {
      "metric": "code_smells",
      "value": "216",
      "bestValue": false
    },
    {
      "metric": "duplicated_files",
      "value": "2",
      "bestValue": false
    },
    {
      "metric": "vulnerabilities",
      "value": "1",
      "bestValue": false
    },
    {
      "metric": "security_hotspots",
      "value": "8",
      "bestValue": false
    }
  ],
  "__branch": {
    "name": "master",
    "isMain": true,
    "type": "LONG",
    "status": {
      "qualityGateStatus": "ERROR",
      "bugs": 6,
      "vulnerabilities": 1,
      "codeSmells": 216
    },
    "analysisDate": "2023-09-07T14:38:41+0200",
    "commit": {
      "sha": "5b01b6dcb200df0bfd1c66df65be30f9ea5423d8",
      "author": {
        "name": "Username",
        "login": "Username@github",
        "avatar": "9df2ac1caa70b0a67ff0561f7d0363e5"
      },
      "date": "2023-09-07T14:38:36+0200",
      "message": "Merge pull request #21 from PeyGis/test-sonar"
    }
  },
  "__link": "https://sonarcloud.io/project/overview?id=PeyGis_Chatbot_For_Social_Media_Transaction"
}
Issue response data (Click to expand)
{
  "key": "AYhnRlhI0rLhE5EBPGHW",
  "rule": "xml:S1135",
  "severity": "INFO",
  "component": "PeyGis_Chatbot_For_Social_Media_Transaction:node_modules/json-schema/draft-zyp-json-schema-04.xml",
  "project": "PeyGis_Chatbot_For_Social_Media_Transaction",
  "line": 313,
  "hash": "8346d5371c3d1b0d1d57937c7b967090",
  "textRange": {
    "startLine": 313,
    "endLine": 313,
    "startOffset": 3,
    "endOffset": 56
  },
  "flows": [],
  "status": "OPEN",
  "message": "Complete the task associated to this \"TODO\" comment.",
  "effort": "0min",
  "debt": "0min",
  "assignee": "Username@github",
  "author": "email@gmail.com",
  "tags": [],
  "creationDate": "2018-04-06T02:44:46+0200",
  "updateDate": "2023-05-29T13:30:14+0200",
  "type": "CODE_SMELL",
  "organization": "peygis",
  "cleanCodeAttribute": "COMPLETE",
  "cleanCodeAttributeCategory": "INTENTIONAL",
  "impacts": [
    {
      "softwareQuality": "MAINTAINABILITY",
      "severity": "LOW"
    }
  ],
  "__link": "https://sonarcloud.io/project/issues?open=AYhnRlhI0rLhE5EBPGHW&id=PeyGis_Chatbot_For_Social_Media_Transaction"
}
Analysis response data (Click to expand)
{
  "analysisId": "AYpvptJNv89mE9ClYP-q",
  "firstAnalysis": false,
  "measures": {
    "violations_added": "0",
    "violations_fixed": "0",
    "coverage_change": "0.0",
    "duplicated_lines_density_change": "0.0",
    "ncloc_change": "0"
  },
  "branch": {
    "analysisDate": "2023-09-07T12:38:41.279Z",
    "isMain": true,
    "name": "master",
    "commit": {
      "sha": "5b01b6dcb200df0bfd1c66df65be30f9ea5423d8",
      "author": {
        "avatar": "9df2ac1caa70b0a67ff0561f7d0363e5",
        "login": "Username@github",
        "name": "Username"
      },
      "date": "2023-09-07T12:38:36Z",
      "message": "Merge pull request #21 from PeyGis/test-sonar"
    },
    "type": "LONG",
    "status": {
      "qualityGateStatus": "ERROR"
    }
  },
  "__branchName": "master",
  "__analysisDate": "2023-09-07T12:38:41.279Z",
  "__commit": {
    "sha": "5b01b6dcb200df0bfd1c66df65be30f9ea5423d8",
    "author": {
      "avatar": "9df2ac1caa70b0a67ff0561f7d0363e5",
      "login": "Username@github",
      "name": "Username"
    },
    "date": "2023-09-07T12:38:36Z",
    "message": "Merge pull request #21 from PeyGis/test-sonar"
  },
  "__project": "PeyGis_Chatbot_For_Social_Media_Transaction"
}
Portfolio response data (Click to expand)
{
  "key": "GetPort_SelfService",
  "name": "GetPort SelfService",
  "desc": "Test",
  "qualifier": "VW",
  "visibility": "public",
  "selectionMode": "NONE",
  "subViews": [
    {
      "key": "GetPort_SelfService_Second",
      "name": "GetPort SelfService Second",
      "qualifier": "SVW",
      "selectionMode": "NONE",
      "subViews": [
        {
          "key": "GetPort_SelfService_Third",
          "name": "GetPort SelfService Third",
          "qualifier": "SVW",
          "selectionMode": "NONE",
          "subViews": [],
          "referencedBy": []
        },
        {
          "key": "Port_Test",
          "name": "Port Test",
          "qualifier": "SVW",
          "selectionMode": "NONE",
          "subViews": [],
          "referencedBy": []
        }
      ],
      "referencedBy": []
    },
    {
      "key": "Python",
      "name": "Python",
      "qualifier": "SVW",
      "selectionMode": "NONE",
      "subViews": [
        {
          "key": "Time",
          "name": "Time",
          "qualifier": "SVW",
          "selectionMode": "NONE",
          "subViews": [
            {
              "key": "port_ayodeji",
              "name": "port-ayodeji",
              "qualifier": "SVW",
              "selectionMode": "NONE",
              "subViews": [
                {
                  "key": "port_ayodeji:REferenced",
                  "name": "REferenced",
                  "qualifier": "VW",
                  "visibility": "public",
                  "originalKey": "REferenced"
                }
              ],
              "referencedBy": []
            }
          ],
          "referencedBy": []
        }
      ],
      "referencedBy": []
    },
    {
      "key": "GetPort_SelfService:Authentication_Application",
      "name": "Authentication Application",
      "desc": "For auth services",
      "qualifier": "APP",
      "visibility": "private",
      "selectedBranches": [
        "main"
      ],
      "originalKey": "Authentication_Application"
    }
  ],
  "referencedBy": [
    {
      "key": "GetPort_SelfService:Authentication_Application",
      "name": "Authentication Application",
      "desc": "For auth services",
      "qualifier": "VW",
      "visibility": "private",
      "selectedBranches": [
        "main"
      ],
      "originalKey": "Authentication_Application"
    }
  ]
}

Mapping Result​

The combination of the sample payload and the Ocean configuration generates the following Port entity:

Project entity in Port (Click to expand)
{
  "identifier": "PeyGis_Chatbot_For_Social_Media_Transaction",
  "title": "Chatbot_For_Social_Media_Transaction",
  "blueprint": "sonarQubeProject",
  "team": [],
  "properties": {
    "organization": "peygis",
    "link": "https://sonarcloud.io/project/overview?id=PeyGis_Chatbot_For_Social_Media_Transaction",
    "lastAnalysisDate": "2023-09-07T12:38:41.000Z",
    "numberOfBugs": 6,
    "numberOfCodeSmells": 216,
    "numberOfVulnerabilities": 1,
    "numberOfHotSpots": 8,
    "numberOfDuplications": 2,
    "mainBranch": "master",
    "tags": []
  },
  "relations": {},
  "icon": "sonarqube"
}
Issue entity in Port (Click to expand)
{
  "identifier": "AYhnRlhI0rLhE5EBPGHW",
  "title": "Complete the task associated to this \"TODO\" comment.",
  "blueprint": "sonarQubeIssue",
  "team": [],
  "properties": {
    "type": "CODE_SMELL",
    "severity": "INFO",
    "link": "https://sonarcloud.io/project/issues?open=AYhnRlhI0rLhE5EBPGHW&id=PeyGis_Chatbot_For_Social_Media_Transaction",
    "status": "OPEN",
    "assignees": "Username@github",
    "tags": [],
    "createdAt": "2018-04-06T00:44:46.000Z"
  },
  "relations": {
    "sonarQubeProject": "PeyGis_Chatbot_For_Social_Media_Transaction"
  },
  "icon": "sonarqube"
}
Analysis entity in Port (Click to expand)
{
  "identifier": "AYpvptJNv89mE9ClYP-q",
  "title": "Merge pull request #21 from PeyGis/test-sonar",
  "blueprint": "sonarQubeAnalysis",
  "team": [],
  "properties": {
    "branch": "master",
    "fixedIssues": 0,
    "newIssues": 0,
    "coverage": 0,
    "duplications": 0,
    "createdAt": "2023-09-07T12:38:41.279Z"
  },
  "relations": {
    "sonarQubeProject": "PeyGis_Chatbot_For_Social_Media_Transaction"
  },
  "icon": "sonarqube"
}
Portfolio entity in Port (Click to expand)
{
  "identifier": "GetPort_SelfService",
  "title": "GetPort SelfService",
  "blueprint": "sonarQubePortfolio",
  "properties": {
    "description": null,
    "visibility": "PUBLIC",
    "selectionMode": "NONE",
    "disabled": null
  },
  "relations": {
    "subPortfolios": [
      "GetPort_SelfService_Second",
      "Python"
    ],
    "referencedBy": [
      "GetPort_SelfService:Authentication_Application"
    ]
  }
}

Alternative installation via webhook​

While the Ocean integration described above is the recommended installation method, you may prefer to use a webhook to ingest data from SonarQube. If so, use the following instructions:

Webhook installation (click to expand) (Click to expand)

In this example you are going to create a webhook integration between SonarQube's SonarCloud and Port, which will ingest SonarQube code quality analysis entities.

Port configuration

Create the following blueprint definition:

SonarQube analysis blueprint (Click to expand)
{
  "identifier": "sonarCloudAnalysis",
  "description": "This blueprint represents a SonarCloud Analysis in our software catalog",
  "title": "SonarCloud Analysis",
  "icon": "sonarqube",
  "schema": {
    "properties": {
      "serverUrl": {
        "type": "string",
        "format": "url",
        "title": "Server URL"
      },
      "projectName": {
        "type": "string",
        "title": "Project name"
      },
      "projectUrl": {
        "type": "string",
        "format": "url",
        "title": "Project URL"
      },
      "branchName": {
        "type": "string",
        "title": "Branch Name"
      },
      "branchType": {
        "type": "string",
        "title": "Branch Type"
      },
      "branchUrl": {
        "type": "string",
        "format": "url",
        "title": "Branch URL"
      },
      "qualityGateName": {
        "type": "string",
        "title": "Quality Gate Name"
      },
      "qualityGateStatus": {
        "type": "string",
        "title": "Quality Gate Status",
        "description": "General status of quality checks"
      },
      "qualityGateConditions": {
        "type": "array",
        "items": {
          "type": "object"
        },
        "title": "Quality Gate Conditions",
        "description": "Conditions of the qaulity gate"
      },
      "status": {
        "type": "string",
        "title": "General Status"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "relations": {}
}

Create the following webhook configuration using Port's UI:

SonarQube analysis webhook configuration (Click to expand)

  1. Basic details tab - fill the following details:

    1. Title : SonarQube mapper;
    2. Identifier : sonarqube_mapper;
    3. Description : A webhook configuration to map SonarQube alerts to Port;
    4. Icon : sonarqube;

  2. Integration configuration tab - fill the following JQ mapping:

    [
      {
        "blueprint": "sonarCloudAnalysis",
        "entity": {
          "identifier": ".body.taskId",
          "title": ".body.project.name + \"-\" + .body.taskId",
          "properties": {
            "serverUrl": ".body.serverUrl",
            "status": ".body.status",
            "projectName": ".body.project.name",
            "projectUrl": ".body.project.url",
            "branchName": ".body.branch.name",
            "branchType": ".body.branch.type",
            "branchUrl": ".body.branch.url",
            "qualityGateName": ".body.qualityGate.name",
            "qualityGateStatus": ".body.qualityGate.status",
            "qualityGateConditions": ".body.qualityGate.conditions"
          }
        }
      }
    ]

  3. Scroll down to Advanced settings and input the following details:

    1. secret: WEBHOOK_SECRET;
    2. Signature Header Name : x-sonar-webhook-hmac-sha256;
    3. Signature Algorithm : Select sha256 from dropdown option;
    4. Click Save at the bottom of the page.

    Remember to replace the WEBHOOK_SECRET with the real secret you specify when creating the webhook in SonarCloud.

Create a webhook in SonarCloud

  1. Go to SonarCloud and select a project you want to configure a webhook for;
  2. Click on Administration at the bottom left of the page and select Webhooks;
  3. Click on Create
  4. Input the following details:
    1. Name - use a meaningful name such as Port Webhook;
    2. URL - enter the value of the url key you received after creating the webhook configuration;
    3. Secret - enter the secret value you specified when creating the webhook;
  5. Click Create at the bottom of the page.
tip

In order to view the different payloads and events available in SonarQube webhooks, look here

Done! any new analysis you run (for example, on new PRs or changes to PRs) will trigger a webhook event that SonarCloud will send to the webhook URL provided by Port. Port will parse the events according to the mapping and update the catalog entities accordingly.

Let's Test It

This section includes a sample webhook event sent from SonarQube when a code repository is scanned for quality assurance. In addition, it includes the entity created from the event based on the webhook configuration provided in the previous section.

Payload

Here is an example of the payload structure sent to the webhook URL when a SonarQube repository is scanned:

Webhook event payload (Click to expand)
{
  "serverUrl": "https://sonarcloud.io",
  "taskId": "AYi_1w1fcGD_RU1S5-r_",
  "status": "SUCCESS",
  "analysedAt": "2023-06-15T16:15:05+0000",
  "revision": "575718d8287cd09630ff0ff9aa4bb8570ea4ef29",
  "changedAt": "2023-06-15T16:15:05+0000",
  "project": {
    "key": "Username_Test_Python_App",
    "name": "Test_Python_App",
    "url": "https://sonarcloud.io/dashboard?id=Username_Test_Python_App"
  },
  "branch": {
    "name": "master",
    "type": "LONG",
    "isMain": true,
    "url": "https://sonarcloud.io/dashboard?id=Username_Test_Python_App"
  },
  "qualityGate": {
    "name": "My Quality Gate",
    "status": "ERROR",
    "conditions": [
      {
        "metric": "code_smells",
        "operator": "GREATER_THAN",
        "value": "217",
        "status": "ERROR",
        "errorThreshold": "5"
      },
      {
        "metric": "ncloc",
        "operator": "GREATER_THAN",
        "value": "8435",
        "status": "ERROR",
        "errorThreshold": "20"
      },
      {
        "metric": "new_branch_coverage",
        "operator": "LESS_THAN",
        "status": "NO_VALUE",
        "errorThreshold": "1"
      },
      {
        "metric": "new_sqale_debt_ratio",
        "operator": "GREATER_THAN",
        "value": "1.0303030303030303",
        "status": "OK",
        "errorThreshold": "5"
      },
      {
        "metric": "new_violations",
        "operator": "GREATER_THAN",
        "value": "3",
        "status": "ERROR",
        "errorThreshold": "1"
      }
    ]
  },
  "properties": {}
}

Mapping Result

The combination of the sample payload and the webhook configuration generates the following Port entity:

{
  "identifier": "AYi_1w1fcGD_RU1S5-r_",
  "title": "Test_Python_App-AYi_1w1fcGD_RU1S5-r_",
  "blueprint": "sonarCloudAnalysis",
  "properties": {
    "serverUrl": "https://sonarcloud.io",
    "status": "SUCCESS",
    "projectName": "Test_Python_App",
    "projectUrl": "https://sonarcloud.io/dashboard?id=Username_Test_Python_App",
    "branchName": "master",
    "branchType": "LONG",
    "branchUrl": "https://sonarcloud.io/dashboard?id=Username_Test_Python_App",
    "qualityGateName": "My Quality Gate",
    "qualityGateStatus": "ERROR",
    "qualityGateConditions": [
      {
        "metric": "code_smells",
        "operator": "GREATER_THAN",
        "value": "217",
        "status": "ERROR",
        "errorThreshold": "5"
      },
      {
        "metric": "ncloc",
        "operator": "GREATER_THAN",
        "value": "8435",
        "status": "ERROR",
        "errorThreshold": "20"
      },
      {
        "metric": "new_branch_coverage",
        "operator": "LESS_THAN",
        "status": "NO_VALUE",
        "errorThreshold": "1"
      },
      {
        "metric": "new_sqale_debt_ratio",
        "operator": "GREATER_THAN",
        "value": "1.0303030303030303",
        "status": "OK",
        "errorThreshold": "5"
      },
      {
        "metric": "new_violations",
        "operator": "GREATER_THAN",
        "value": "3",
        "status": "ERROR",
        "errorThreshold": "1"
      }
    ]
  },
  "relations": {}
}