Skip to main content

Automated Pull Requests

Nexus Lifecycle can open new pull requests to update dependencies to versions without policy violations. Whenever a scan of your SCM repository's default branch finds a component with a policy violation and a newer version without the policy violation, Lifecycle will attempt to bump the component to the newer version. This approach is the preferred way to remediate a policy violation. The pull request contains links to the full Lifecycle report that triggered it, as well as links to any security vulnerability details.

Supported platforms: Bitbucket Cloud, Bitbucket Server, GitHub, GitLab

Supported ecosystems: Maven, NPM, Gradle, Go

Prerequisites

To use Automatic Pull Requests:

Topic

Requirement

Ecosystem

Maven, NPM, Gradle, Go

Platform

Azure DevOps, Bitbucket Cloud, Bitbucket Server, GitHub.com, GitHub Enterprise, Gitlab

Repository Visibility

Repositories must be set to Private. Exceptions are GitHub Enterprise, which permits any visibility, and GitLab, which allows for Private or Internal repositories.

Token

You must have a token for your SCM system, and the token permissions must be configured correctly.

Manifest

The source repository must contain a manifest, like a pom.xml file, that includes version data for included components.

Repository URL

Your Application inside IQ Server must have a repository URL, which much be entered as an HTTPS, e.g. https://github.com/samplecount/samplerepo. The trailing .git is optional. If an ssh:// URL is used, Lifecycle will attempt to convert it to HTTPS. The .git:// style URL is not supported. Also note that the same URL may be used for multiple applications.

Pull Request option

The Automated Remediation Pull Request option must be enabled.

Default Branch

Your repository must have a default branch to use as the "base branch" for the pull request. The default value is the master branch.

IQ Server Build Stage

Any except for the develop stage.

Also, note that the repository URL is configured at the Application level, but the other attributes can be at the Application, Organization, or Root Organization level.

The following diagram illustrates the ways that the creation of an automated remediation pull request can be triggered.

137203329.png

IQ Server Clone Directory Configuration

For each configured application, the repository will be cloned on the host that the IQ Server runs on. The default location is:

<sonatypeWork>/source-control

Note that the default for sonatypeWork is ./sonatype-work/clm-server.

To change the location of the repository clone for IQ Server Release 140 and later, use the Source Control Configuration REST API.

For release 139 and earlier, use the config.yml

sourceControl:
  cloneDirectory: /your/path/here

Note that if the cloneDirectory does not have a leading "/", then the path will be relative to <sonatypeWork> .

Understanding Automated Pull Requests

The Automated Pull Request functionality behaves in a specific, predictable way:

  • The automated pull request workflow is triggered whenever your SCM repository's base branch is scanned.

  • Automated Pull Requests only work on components. It does not find or fix other vulnerabilities in your code.

  • Automated Pull Requests only bumps components to non-violating versions. It does not take any other remediation action. Review the pull requests and the linked Lifecycle report thoroughly to see other remediation options.

  • A manifest file with component version information must be included in the repository. E.G. a pom.xml file

  • The Automated Pull Request follows a hierarchy when selecting a new component version:

    • If a version resolves violations for the target component and violations for that component's transitive dependencies, that version is used.

    • Otherwise, a version that resolves all violations for the target component is used.

    • If neither of the above is true, then no pull request is generated.

  • Solving transitive dependencies alone is not currently supported.

    • This means that, if bumping versions would only remediation a violation in a transitive dependency, no pull request will be created.

Note

Remember, the Automated Pull Request feature only bumps to component versions that are free from all violations. It will not bump to a version with fewer violations or less severe violations.

Reading an Automated Pull Request

Pull requests generated by the Automated Pull Request feature look like the example below, and contain useful information that helps developers evaluate the pull request for appropriateness.

126658069.png

  1. The description calls out the component or components being addressed by the pull request, along with the component versions.

  2. The Policy table shows which policy or policies are being violated.

  3. This section shows the Application and Organization's name as it exists inside IQ Server. It also shows the date of the evaluation and the IQ Server build stage associated with the evaluation.

  4. This link takes users to the full Lifecycle evaluation report associated with the pull request.

Automated Pull Request Daily Activity

The Source Control Configuration Overview screen displays recent activity related to automated pull request creation.

126654535.png

Summary information for each attempt to create a pull request will be shown in a table. This information is purged on a daily rotating basis determined by when the server was last started, so at any time a maximum of 24 hours of results is shown.

Breaking Changes

If a pull request bumps a component to a different version that is likely to break the application, the pull request will inform the developer of these breaking changes, as in the image below.

example of a breaking changes notification in a pull request

Breaking Changes alerts the developer that this remediation path will require some extra effort. For more information about the violation and other potential remediation paths or strategies, users can click View Full Report at the bottom of the Pull Request.