Using Lift
The two ways to get value from Lift are to analyze a repository branch and to get live feedback on a pull request. These are described below.
Analyzing is generally done when you first integrate Lift to see the overall health of a repository or occasionally over time with pull requests. The pull request workflow is a real time way to see newly introduced bugs before they are merged into your core product.
Analyzing Repositories
When visiting the Lift Console, you will see a list showing all repositories the Lift app is installed on. Each organization is shown separately and can be changed via the dropdown (e.g. jtomsonatype in the screenshot that follows).
From this screen, you can select any repository for Lift to get started analyzing. After doing so, select the branch from the dropdown you wish to scan and click the Analyze button. You will then be forwarded to the analysis view where you can see details of Lift inspecting your code.
The message on the page (shown above) and a yellow coloring in the branch list indicates that Lift is building and analyzing your code. This can take some real time (roughly twice the normal build time of your project), so feel free to stretch, grab a cup of coffee or whatever. Lift will take it from here.
While analyzing, the page provides you with details of when the analysis started. If you'd like real time updates, you can check the Build Logs tab.
Once Lift has finished analysis, the Results tab will show any issues found or congratulate you if there are none. The approximate time the analysis completed is shown and an exact time can be seen if you hover over the approximation.
The information from the Results tab does not include vulnerabilities found. Those are shown in the Dependencies tab, as described below.
After a successful scan, the Dependencies tab will show you a breakdown of components and any vulnerabilities within your repository and branch. You can see more details about this tab in Dependency View.
The Tool Results tab shows you a list of each tool that the scan attempted to run as well as if it succeeded or failed. This information may be mirrored in the build log.
If there is a problem with analysis you can click to see the failing build log in the Build Logs tab. The Troubleshooting page offers additional guidance if there is a build error.
Finally, the Technical Debt tab (currently in Beta) shows you applicable results for any identified technical debt that Lift has found in your repository. The Beta implementation currently only works on Java projects that use Maven or Gradle. You can see more about it in application or on the Prioritizing Technical Debt page.
Even without a repository scan, repositories with Lift installed will be analyzed every time you create a pull request in GitHub as described below.
Lift in Pull Requests
Lift's pull request workflow is the primary way to interact with Lift. Once you have installed Lift on a repository which it can build and analyze (see above), you are ready to use the pull request workflow. Lift will automatically analyze your repository each time a pull request is submitted to your repository, comparing the source and destination branches.
After analysis, Lift will report any introduced bugs that it finds as line comments on the GitHub pull request diff. Any bugs not introduced by the pull request or falling outside of the diff won't be shown; if you want to see them then you can run an analysis on the Lift Console for that repository, as described above.
Lift will also take advantage of GitHub's status API to let you know if there were any new bugs introduced by the pull request:
Note that Lift does not block a pull request on anything it finds and just shares information. Lift does act as a check however so if your repository is set to block on failed checks, it will block per that configuration.
Lift Code Suggestions
The analyzers within Lift provide code suggestions, when available. This is in addition to reporting bugs or errors. These suggestions are provided on a Github PR as part of a comment by LiftBot. For example:
How to use
The best ways to implement these suggestions are the following:
- Lift’s Auto-fix: This option allows you to preview the suggested fixes and make sure they do not break your code before committing the suggestions. More details are below.
- Commit suggestion: This option appears on GitHub automatically when a suggestion is provided. Clicking on this button in the comment creates its own commit for the suggestion.
- Add suggestions to batch: Using this Github feature allows you to add all suggestions to a single commit. More details can be found here.
Note: The suggestions do not appear in every comment by LiftBot on the PR. They automatically show up, when available. No action is needed to enable this feature.
Lift Auto-fix
When pull request comments from Lift contain suggestions from specific tools it will also comment with directions on how to use the Auto-fix feature. This allows you to preview the suggested fixes and make sure they do not break your code before committing the suggestions. Additionally, some tool suggestions made by Lift may contain changes to package imports which can't be done through GitHub's inline suggestion feature. The Lift Auto-fix feature enables more context to be applied when fixing issues in your local workspace.
Here's an example of what you'd see:
This message will appear once in a given PR. The Auto-fix patch URL represents the the last successful check of your pull request. If all issues have been resolved the URL will return a 404. If only a subset of the commented findings remain the Auto-fix patch URL will return a patch to resolve only those remianing findings. Currently, only ErrorProne findings with remediation will apply.
The pull request workflow is the best way to use Lift. It will give you feedback on your code changes without any additional effort. Especially if you are already using a pull request-based workflow, Lift will simply be there like a trusted teammate, always ready to give you a thorough code review. Now that you have the basics down, check out the Configuration Guide to get the most out of Lift.
Having any problems? See our troubleshooting page for a pull-request example to make sure everything is configured properly.
Badge
Why not add a badge to your documentation to show that your repository is protected by Sonatype Lift? To do so, simply add the following link into your markdown of your README.md or equivalent:
https://lift.sonatype.com/api/badge/<host>/<owner>/<repo>
For example: https://lift.sonatype.com/api/badge/github.com/sonatype/nexus-public