# Automated remediation Sonatype Lifecycle can create new pull requests (PRs) 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 that hasn't already been identified, and a newer version without the violation is available, Lifecycle will try to update the component to that 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**: Azure DevOps, Bitbucket Cloud, Bitbucket Server, GitHub, GitLab **Supported ecosystems**: Maven, npm, Gradle, Go ### Golden PRs The automated PRs created contain recommendations to upgrade dependencies to Golden Versions, when available. **Note** Automated remediation pull requests are created only for Maven components by default. For other ecosystems, pull requests are not created unless non-golden pull requests are enabled using the Source Control REST API. Refer to [Golden Versions and PRs](https://help.sonatype.com/en/golden-versions-and-prs.html#idp298622) for more details. ### Automated Pull Requests to Update InnerSource Dependencies Sonatype _Lifecycle_ can automatically create new pull requests to update [InnerSource dependencies](https://help.sonatype.com/en/innersource-insight.html) to newer versions. When a new non-major version of an InnerSource component is detected at the release stage during evaluation of an application, automated pull requests to update the older version of the InnerSource component are created in the SCM system. To configure your SCM to enable creation of automated pull requests, refer to [Automated PRs for InnerSource](https://help.sonatype.com/en/automated-prs-for-innersource.html "Automated PRs for InnerSource Components"). ## 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.](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 with GoldenPRs_ 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. | | | --- | | | ## 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: ``` /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](https://help.sonatype.com/en/source-control-configuration-rest-api.html "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 ``. ## Understanding Automated remediation with GoldenPRs behavior 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 no pull request is created when bumping versions would only remediate a violation in a transitive dependency. **Component Versions Recommended by Automated PRs** - The Automated PR 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. - The Automated PR will not recommend or bump to any pre-release versions of a component. For example, component versions like canary, ea, nightly, milestone, alpha, beta, pre, preview, dev, snapshot etc. will be excluded. ## Golden-only automated pull request behavior Automated remediation pull requests create pull requests only for Golden Versions by default. **Note** InnerSource components are not affected by this behavior and continue to receive automated pull requests when a remediation version is available. - For Maven components, pull requests are created only when a Golden Version is available. - For non-Maven components, pull requests are not created by default because Golden Version data is not available. Non-golden pull requests can be enabled using the Source Control REST API. For instructions, see Enable non-Golden automated pull requests. There is no UI option for enabling non-golden pull requests. ## 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. | | | --- | | | 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. ## Daily Automated Pull Requests The Source Control Configuration Overview screen displays recent activity related to automated pull request creation. 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. **How to Access Daily Automated Pull Requests:** 1. Log in to Sonatype **IQ Server**. 2. Navigate to **Applications**. 3. Select the **IQ application** for which source control is configured. 4. Scroll down to the **Source Control** section. 5. Under Configuration, click the **configured source control** entry (for example, the repository URL). The **Source Control Configuration** page opens. 6. Scroll to the bottom of the **Source Control Configuration** page. 7. View the **Daily Automated Pull Requests** table, which displays recent automated pull request activity. The _Daily Automated Pull Requests_ table displays the daily automated PR activity. Hover on the icons in the _Status_ column for a description of the reasons indicating a successful/unsuccessful PR creation. | Status | Description | | :-: | --- | | | Indicates that a direct dependency in the project configuration could not be found. | | | Indicates that a PR was created successfully to remediate the policy violation. | | | Indicates an error occurred while creating this PR. Check server logs for more information. | The _Time Spent_ shows the total time taken in milliseconds, to checkout, remediate, push, and create the PR. The _Start Time_ shows the timestamp and time zone when the process to create the automated PR was initiated. ## 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. | | | --- | | | 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.