Pull Request Commenting

NEW IN RELEASE 88

Overview

Nexus IQ for SCM adds a comment to a pull request (PR) for repositories configured for source control when the PR introduces a new policy violation.  Note, the terminology for GitLab is merge request (MR).

This is accomplished by comparing the policy evaluation report of the pull request's source branch with the latest available policy evaluation report for the source control configured default branch.

IQ server will only create pull request comments for private or internal repositories, with one exception. For GitHub Enterprise IQ server can also comment on public repositories.

Azure DevOps, Bitbucket Server, GitHub, and GitLab are supported for PR Summary Comments and PR Line Comments.

  • For Azure DevOps Server, version 2019+ is required.
  • For Bitbucket Server, version 6.7+ is required as the necessary APIs are not available prior to that version.
  • For GitLab, version 11+ is required as the necessary APIs are not available prior to that version.

The PR comment reports Threat Level Low, Medium, and High (2-10) and excludes the Informational level (0 and 1) to keep development focus on policy violations that require most attention.

Prerequisites

The following criteria are prerequisites for PR commenting:

  1. The selected repository is configured for source control, as described in Nexus IQ for SCM.
  2. Nexus IQ policy evaluations are being run against the source control configured default branch commits. We recommend this configuration for the CI system.
  3. Nexus IQ policy evaluations are being run against the feature/development branch commits that the PR pertains to.
  4. Automated pull request commenting will only work on repositories that cannot be accessed publicly.

PR Summary Comment

The PR summary comment contains the summary of violations, affected components, and a description of the violations that were introduced in the PR. Suggested remediation for policy violations are included, if available. The  and  icons that can be seen next to the affected components are used to indicate whether a component is a direct or transitive dependency of the project. For Bitbucket these are shown as text instead of icons (due to a more limited markup).

The policy violation details are collapsed by default for GitHub and GitLab. Developers can expand them as needed. For Bitbucket the policy violation details are fully shown (due to a more limited markup).

If PR line comments are created (more details in the next section), links are added to the associated components for convenience. See an example below (for GitHub):

There is also a section for fixed policy violations if the PR fixes preexisting policy violations.

Important note:  The target branch of the PR is NOT used as the basis for detecting new policy violations. The basis used for comparison is the Nexus IQ for SCM configured default branch.

PR comments are generated when:

  • Policy violation reports are run against new commits for an open PR and violations have been detected
  • Newly detected PRs satisfy the prerequisites for PR commenting

The PR comment is designed to appear on the PR within a few moments after either of these conditions are satisfied.

Nexus IQ for SCM will update existing PR comments with the latest available information if the feature branch scan report is reevaluated, or if a new policy evaluation is run against the head commit for the PR.

The pull request (PR) comment only reports violations introduced or fixed by the specific PR. These violations are determined by comparing the policy evaluation report of the PR's source branch with the latest available policy evaluation report for the Nexus IQ for SCM configured default branch. Note that the Summary and Scan Report shown in the status check section includes all violations present in the latest policy evaluation for a given commit.

PR Line Comments

NEW IN RELEASE 95

An attempt is made to create a line comment for each change that introduces new policy violations. That is not always possible due to the fact that line comments can be only created on lines available in the pull request's file diff. On the other hand, sometimes there are multiple potential locations to comment on for a particular component. In those cases, the most relevant location is chosen for each component in order to keep the number of line comments to a minimum.

Identifying changes that introduce policy violations is ecosystem-specific. For now, the PR line commenting feature is enabled for direct dependencies in Maven, Gradle, NPM, and Go projects. The strategy used to identify the location for the line comments is similar to the one used by the Automated Pull Request feature for version bumping.

Similar to the PR summary comment, PR line comments contain the affected component, the summary, and the description of the violations that were introduced by the change at the line of code to which the comment is attached. A component version that would remediate all policy violations is also included, if available. The policy violation details are expanded by default. An example is shown below (for GitHub):

Breaking Changes

NEW IN IQ SERVER RELEASE 108

Breaking changes information is made available through the Advanced Development Pack add-on feature for Lifecycle. If available, the breaking changes information will inform the developer about the amount of work required to perform the version upgrade whenever suggested remediations for policy violations are included.

In the screenshot below the line starting with a red square and "Multiple breaking changes" was added to the PR comment, based on the breaking changes information available for the suggested remediation.

Transitive Solver

NEW IN IQ SERVER RELEASE 111

If the Advanced Development Pack add-on feature is enabled, remediations that fix policy violations for the target component and its dependencies are preferred, if available, over remediations that only fix policy violations for the component. Otherwise, remediations that fix policy violations for the target component only are used, if such remediations exist.

In the example shown below upgrading to the suggested remediation will fix all policy violations for 'jackson-databind' and its dependencies:

Running Policy Evaluations on Different Branches

We recommend that evaluations against the master branch use the ‘build' stage in Nexus IQ, and that feature branch evaluations are performed against the ‘develop’ stage. The ‘develop’ stage is intended for policy evaluation snapshots where changes to application dependencies and any associated policy violations are not tracked linearly. Because feature branches are volatile and vary across the features developed, using the ‘develop’ stage helps reduce noise by not showing these evaluations on the dashboard or your reports. 

Enabling policy evaluations on feature branches will also increase the amount of disk space consumed by stored application composition reports. Nexus IQ Server can be configured to automatically purge outdated reports, more information on this is available on the Data Retention and Purging page.

Please review the actions in the Nexus IQ Server policy configuration if the feature branch policy evaluation is configured to use the 'develop' stage. By default, using the 'develop' stage will not result in a 'fail' action for any of the defined policies. Status checks, and the associated branch protection only reports failure if the policy evaluation triggers a 'fail' action.