Snyk Git repositories: deployment recommendations

You can integrate Snyk with your Git repository, to quickly and easily gain visibility across all the Snyk Projects that you add to the Projects list in Snyk.
Sny Git repository integrations allow you to:
Continuously perform security scanning across all integrated repositories
Detect vulnerabilities in your open source components
Provide automated fixes
Recommended deployment order
To ensure a smooth deployment for your team, follow the stages outlined below for each integration.
If you try to implement all the SCM integration features at the same time, you risk causing friction in your software development life cycle (SDLC), which in turn leads to a poor developer experience.
Deployment Stages
Configurations
Outcome
​Stage 1​
Set up your Git repository integration
See the configuration documentation for each Git repository integration​
A configured integration, ready to import Projects
​Stage 2​
Import all of the Projects from your Git repository.
• Test both public and private repos
• Disable all user notifications
• Disable Snyk PR checks
• Disable Auto-fix PRs
• Disable Failing PR checks
• Disable Automatic dependency upgrades
A complete Software Bill of Materials (SBOM) that enables you to assess risk across your applications.
​Stage 3​
Developer and Security teams use Snyk prioritization reporting capabilities to build a fix plan.
Watch this video to learn more about Snyk prioritization reporting.
Alignment between Developers and Security on what should be fixed and when streamlines the fix process.
​Stage 4​
Alert developers to issues in real-time, and educate them on available fixes.
• Enable Snyk PR checks and fail PRs if they contain high severity issues with available fixes
• Enable Auto-fix PRs
Improve your organization’s mean-time-to-fix (MTTF).
​Stage 5​
Prevent developers from introducing any new vulnerabilities
• Enable Failing PR checks, for ANY High severity issues (fix or no fix)
‘Secure by Design’ methodology achieved.
​Stage 6​
Reduce technical security debt
• Enable Automatic dependency upgrades​
Reduce future design headaches and hot fixes, which can be time-consuming to research and address.
Stage 1: Set up your Git integration
Snyk has pre-built integrations for Git repositories, including GitHub, GitHub Enterprise, Bitbucket Cloud, and others.
See Set up an integration for details.
SCM permissions on repositories
Operations triggered using the Snyk UI, such as opening a Fix PR or retesting a Project, are performed for the acting user. Thus to perform these operation, you must connect your own SCM user or service account. This gives Snyk the required permissions for the repositories where you would like to perform these operations.
For example, in GitHub, the accounts connected to Snyk need the following access on the target repositories:
Action
Purpose
Required permissions on the repository
Daily / weekly tests
Used to read manifest files in private repos
Write or higher
Snyk tests on pull requests
Used to send pull request status checks when a new PR is created or an existing PR is updated
​
Opening fix and upgrade pull requests
Used to send fix or upgrade PRs in the monitored repos
​
Snyk tests on pull requests - initial configuration
Used to add Snyk webhooks to the imported repos, to notify Snyk when pull requests are created or updated, and enable Snyk to trigger a scan
Admin
Change notification settings
By default, Snyk emails every Org user when a new issue or fix in a Project’s dependencies is found, and provides each user with a weekly update of the security status across the Organization. If you plan to import many Projects to an Organization, to avoid sending multiple email notifications sent to users, consider disabling all the notifications for that Org.
To customize the emails your Org users receive, go to Settings 
 > Notifications > Notification Setting. The changes you make here will affect all of your Organization’s members, although Org users can override these default settings in their user-level account settings.
To disable notifications for all the users in an Org ahead of your import, deselect the appropriate notification boxes. See Notification management for more details.
Stage 2: Import Projects
Go to the Projects page in the Snyk UI, select Add projects, select the repos to import to Snyk, and click Add selected repositories.
Add projects to Snyk
Snyk starts scanning the selected repos for dependency files (for example, package.json) in the entire directory tree and imports these files as Projects.
Snyk evaluates root folders and any custom file locations defined. If no manifest or configuration files are found, Snyk alerts you that no files can be imported.
Snyk detects the manifest files (Projects), tests them, then displays the results.
Imported Projects appear underneath the repository name.
After a Project is imported, it is continuously checked for vulnerabilities.
To confirm that a Project was imported, go to the Add project import page for the integration. Imported projects are indicated by a ✔ next to the repository name: 
​
See Import a Project for more details.
Stage 3: Enable Snyk test on PRs
PR test settings and workflows
By default, Snyk scans every pull request submitted on your monitored repositories and displays the results and recommendations grouped together in a single security check and a single license check.
Security check
Status details
Click the Details link to display the status of the Snyk check. The status options are:
Success: no issues were identified and all checks passed
Processing: this status is displayed until the Snyk test is completed
Failure: identified issues that must be fixed for the check to pass
Error: indicates that one of the following issues may have occurred:
Your manifest file may be out of sync
Snyk could not read the manifest file
Snyk could not find the manifest file
Snyk security check failure
Manage PR test settings
An administrator can manage settings for Snyk PR tests for each SCM integration at the Organization level and apply these settings to all the projects for that integration, or select specific projects to apply the PR tests. You can configure whether this feature is on (enabled by default) and set fail conditions to define when Snyk should fail your PR checks.
To configure the PR test settings for your Organization:
1.For the relevant organization, go to Organization Settings 
 > Integrations, select the relevant integration, and click Edit Settings.
2.Set the the toggle to Enabled and use the dropdown to set the Fail conditions as needed.
3.Click Update settings.
Enable test for PRs and set fail conditions
To manage the PR test settings per Project:
1.To configure the pull request test settings for a specific project, go to Projects > Projects Settings > Edit Settings.
The Project page opens.
2.In the Project page, select the Settings tab in the upper right, and the SCM integration option in the left sidebar.
3.Select and confirm the relevant options in each of the sections.
Select test settings for Project
Use Snyk License policies to ensure that your Snyk PRs are free of licensing issues.
See Licenses for more information.
Initial step: get visibility and set fail conditions
When you first roll out your SCM integration, Snyk recommends that you start with Snyk set up to test your PRs without failing them, so that your developers can get used to seeing the Snyk commit check.
1.Decide to apply PR testing for your integrations at the Organization level, or for specific Projects.
2.Set the Fail conditions as described in the preceding section Manage PR test settings:
Fail only for Only fail when the PR is adding a dependency with issues.
Check both Only Fail for high severity issues and Only fail when the issues found have a fix available.
Stage 4: Enable Blocking PRs
After you have embedded Snyk into your software development life cycle (SDLC), and have built good developer awareness, you can start to apply stricter policies to improve your overall security posture, for example:
Low priority projects: you can fail the PR only for new high severity issues that are fixable.
Medium priority projects: fail the PR only for high severity issues.
High priority projects (PCI/GDPR compliance): fail the PR for any issue.
To align vulnerability severity with your internal policy, use security policies to change the severity of issues and attach them to relevant projects attributes. See Security policies for more details.
Stage 5: Automatic Fix PRs
Snyk scans your Projects on either a daily or a weekly basis. When new vulnerabilities are found, Snyk emails you and opens automated PRs with fixes for the repositories.
The example that follows shows a fix pull request opened by Snyk:
To configure the PR test settings for specific Projects, select the relevant Organization and go to Organization Settings 
 > Integrations > Edit Settings.
PR test settings
Snyk recommends that you exclude patches from the auto fix PRs, if your developers are not familiar with how to use and execute them.
Ask your developers to consider the merge advice label that appears on the auto fix PRs:
Merge advice label
Snyk auto fix PRs are generated only for new issues.
If your SCM is GitHub and you are not using Snyk Broker, then by default, Snyk rotates every Org user's credentials to open the auto fix PRs. You can change this if needed and set the user credentials to open the auto fix PRs. See Opening fix and upgrade pull requests from a fixed GitHub account for details.
Stage 6 - Dependency Upgrade PRs
When your Group is ready to start tackling security technical debt, you can configure Snyk to automatically create pull requests (PRs) on your behalf to upgrade your dependencies.
Automatic upgrade PR
How Automatic upgrade PRs work
1.Integration is configured and users enable automatic upgrade PRs.
2.Snyk scans your Projects as you import them and continues to monitor your Projects, scanning on a regular basis.
3.For each scan, when Snyk identifies new versions for your dependencies:
Snyk creates automatic upgrade PRs (frequency based on Snyk project settings).
Snyk does not open a new upgrade PR for a dependency that is already changed (upgraded or patched) in another open Snyk PR.
Snyk opens separate PRs for each dependency.
Snyk does not create upgrade PRs for a repo that has five (5) or more Snyk PRs open. If the limit of open PRs is reached, no new ones are created. This number can be set to between 1 and 10 from the settings. This limit only applies when creating upgrade PRs, but does count fix PRs. Fix PRs are not limited in this way.
By default, Snyk recommends only patch and minor upgrades, but major version upgrade can be enabled in the settings where the feature is enabled.
If the latest eligible version contains vulnerabilities not already found in your Project, Snyk does not recommend an upgrade.
Snyk does not recommend upgrades to versions that are less than 21 days old. This is to avoid versions that introduce functional bugs and subsequently get unpublished, or versions that are released from a compromised account (where the account owner has lost control to someone with malicious intent).
Supported languages and repos
Snyk currently supports automatic upgrade PRs for npm, Yarn, and Maven-Central projects through GitHub, GitHub Enterprise Server, and BitBucket Cloud, including use of the Snyk Broker. For use with the Broker, ask your admin first to upgrade to v4.55.0 or later.
Enable automatic dependency upgrade PRs for a specific project
To set PR Settings on the Project level and override the PR settings configured at the Organization level:
1.Open the Organization for which you would like to enable automatic upgrade PRs and go to the Projects tab.
2.Select and expand the relevant Project, select the relevant Target, and using the cog icon, open the Settings:
​
​
3.In the Settings area, in the left panel menu, click the Integration settings to apply unique settings for that specific Project.
4.In settings that load, scroll to the Automatic dependency upgrade pull requests and click Disabled.
5.In the options that appear:
1.Snyk creates PRs up to a maximum of 10 open simultaneously per repo.
To limit this number further, select the maximum number of PRs from the dropdown list.
For more information, see Upgrading dependencies with automatic PRs.
2.In the Dependencies to ignore field, enter the exact name of any dependencies that should not be handled as part of the automatic functionality.
This field accepts only lower case letters.
3.After you click Upgrade dependency settings, each time Snyk scans this Project, Snyk automatically submits upgrade PRs based on the scan results.
If a newer version is released for an existing Snyk upgrade PR or for an existing fix PR, before Snyk can raise a new PR, the existing PR must be closed or merged.
Automatic dependency pull request settings

Introduction to Git repositories

Using GitHub or GitHub Enterprise

Last modified 7d ago

Action	Purpose	Required permissions on the repository
Daily / weekly tests	Used to read manifest files in private repos	*Write* or higher
Snyk tests on pull requests	Used to send pull request status checks when a new PR is created or an existing PR is updated
Opening fix and upgrade pull requests	Used to send fix or upgrade PRs in the monitored repos
Snyk tests on pull requests - initial configuration	Used to add Snyk webhooks to the imported repos, to notify Snyk when pull requests are created or updated, and enable Snyk to trigger a scan	*Admin*

Deployment Stages	Configurations	Outcome
Stage 1 Set up your Git repository integration	See the configuration documentation for each Git repository integration	A configured integration, ready to import Projects
Stage 2 Import all of the Projects from your Git repository.	• Test both public and private repos • Disable all user notifications • Disable Snyk PR checks • Disable Auto-fix PRs • Disable Failing PR checks • Disable Automatic dependency upgrades	A complete Software Bill of Materials (SBOM) that enables you to assess risk across your applications.
Stage 3 Developer and Security teams use Snyk prioritization reporting capabilities to build a fix plan.	Watch this video to learn more about Snyk prioritization reporting.	Alignment between Developers and Security on what should be fixed and when streamlines the fix process.
Stage 4 Alert developers to issues in real-time, and educate them on available fixes.	• Enable Snyk PR checks and fail PRs if they contain high severity issues with available fixes • Enable Auto-fix PRs	Improve your organization’s mean-time-to-fix (MTTF).
Stage 5 Prevent developers from introducing any new vulnerabilities	• Enable Failing PR checks, for ANY High severity issues (fix or no fix)	‘Secure by Design’ methodology achieved.
Stage 6 Reduce technical security debt	• Enable Automatic dependency upgrades	Reduce future design headaches and hot fixes, which can be time-consuming to research and address.