Pull Request Commenting
NEW IN RELEASE 88
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 policy evaluation report for the common ancestor commit between the pull request's source and target branches, if such report exists, or
- the latest policy evaluation report for the pull request's base commit, which is the head commit of the pull request's target branch at the moment the pull request was created, if such report exists, or
- the latest available policy evaluation report for the source control configured default branch.
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.
The following criteria are prerequisites for PR commenting:
- The selected repository is configured for source control, as described in Nexus IQ for SCM.
- Nexus IQ policy evaluations are being run against the source control configured default branch commits. We recommend this configuration for the CI system.
- Nexus IQ policy evaluations are being run against the feature/development branch commits that the PR pertains to.
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.
PR Summary Comment
The PR summary comment contains the summary of policy violations, affected components, and a description of the policy violations that were introduced in the PR. Suggested remediation for policy violations are included, if available. Theand 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.
PR comments are generated when:
- Policy evaluation reports are run against new commits for an open PR and new policy violations have been detected or existing policy violations have been fixed.
- 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 policy evaluation 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 policy violations introduced or fixed by the specific PR. These policy violations are determined by comparing two policy evaluation reports as described above in the Overview section. Note that the Summary and Application Report shown in the status check section includes all policy 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 policy 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 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.
If you experience challenges with seeing Transitive Solver recommendations, please refer to this Knowledgebase article.
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 policy evaluations against the default branch use the ‘build' stage in Nexus IQ, and that all other branches 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/development 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.