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.

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

  • 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 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 status check 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 amount 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):

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 trigger a 'fail' action.