Links
Comment on page

Snyk GitHub integration

Feature availability
The Snyk GitHub integration is available for all Snyk customers regardless of plan level. See the Plans and Pricing page for more details.

Prerequisites for Snyk GitHub integration

  • Internet-accessible repositories. If your repositories are not internet-accessible, you must use Snyk Broker.
  • A public or private GitHub project.

Known limitations of the Snyk GitHub integration

You cannot use the Snyk GitHub integration with a Snyk Service Account, as the GitHub integration is associated with your user account, not with the Snyk Organization. Use the GitHub Enterprise integration to import public and private Projects using the API with a Snyk Service Account.

Snyk GitHub integration features

The Snyk GitHub integration allows you to:
  • Continuously perform security scanning across all the integrated repositories
  • Detect vulnerabilities in your open-source components
  • Provide automated fixes and upgrades

Per user, not per Organization

The GitHub integration is set up for your user account, not for a Snyk Organization. GitHub integration settings apply to all Organizations associated with your user account but do not automatically apply to other user accounts in an Organization.
When you import a Snyk Project using your GitHub integration with the Snyk PR functionality enabled, Snyk PRs are created for that Project. However, if another user imports Projects with their GitHub integration after disabling the Snyk PR functionality, Snyk PRs are not created for the Projects they import.

How to set up the Snyk GitHub integration

To connect your GitHub repositories to Snyk for scanning, you need to set up the integration and then import Projects.
See Set up an integration and Import a Project for details of this process.

Snyk GitHub integration settings

To see all settings for your GitHub integration, go to the Snyk GitHub Integration settings page, then go to
Settings
Organization Settings, and select GitHub in the Integrations section:
GitHub integration settings
GitHub integration settings
You can then scroll down to the section required, and set the options accordingly:

General Snyk GitHub integration settings

Select General to view general settings:
GitHub general settings
GitHub general settings
  • Integration ID: The unique ID for this integration; needed if you use the Snyk API.
  • Repository access: Whether Snyk can access private repos (in addition to public repos). Changing this setting affects existing Projects.

Snyk GitHub integration features

After you have connected GitHub to Snyk, you can use:

Project-level security reports

Feature availability Reports are available with Enterprise plans. See the plans and pricing page for details.
Snyk produces advanced security reports that let you explore the vulnerabilities found in your repositories and fix them right away by opening a fix pull request directly in your repository, with the required upgrades or patches.
This example shows a Project-level security report.
Project-level security report
Project-level security report

Project monitoring and automatic fix pull requests

Snyk scans your Projects on either a daily or a weekly basis. When new vulnerabilities are found, Snyk notifies you via email and opens automated pull requests with fixes for your repositories.
The example that follows shows a fix pull request opened by Snyk.
Fix pull request opened by Snyk
Fix pull request opened by Snyk
To review and adjust the automatic fix pull request settings in the Snyk GitHub Integration settings page, go to
Settings
Organization Settings > Integrations > Source control > GitHub.
Scroll down to the Automatic fix PRs section and set the options accordingly:
Automatic fix pull request settings
Automatic fix pull request settings

Commit signing

Feature availability For availability with Snyk Broker, see the Commit signing page in the Broker docs.
All the commits in Snyk's pull requests are done by [email protected] (a verified user on GitHub), and signed with a PGP key. All Snyk pull requests appear as verified on GitHub, thus providing your developers with the confidence that the fix and upgrade pull requests are generated by a trusted source.

Pull request status checks

The Snyk PR Checks feature allows Snyk to test any new PR in your repositories for security vulnerabilities and sends a status check to GitHub. This lets you see, directly in GitHub, whether or not the pull request introduces new security issues.
This example shows how Snyk PR checks appear on the GitHub pull request page.
Snyk pull request checks on GitHub pull request page
Snyk pull request checks on GitHub pull request page
You can review and adjust the pull request test settings using the Snyk GitHub Integration settings page in
Settings
Organization Settings > Integrations > Source control > GitHub.
Pull request status checks settings
Pull request status checks settings

Required permissions scope for the Snyk GitHub integration

The table that follows provides a summary of the required access scopes for GitHub integration. For information about the token in a brokered integration, see GitHub - install and configure using Docker. For details about permissions in a non-brokered integration, refer to the information that follows this table.
Action
Purpose
Required permissions in GitHub
Daily / weekly tests
Used to read manifest files in private repositories.
repo (all)
Manual fix pull requests (triggered by the user)
Used to create fix PRs in the monitored repositories.
repo (all)
Automatic fix and upgrade pull requests
Used to create fix or upgrade PRs in the monitored repositories.
repo (all)
Snyk tests on pull requests
Used to send pull request status checks whenever a new PR is created or an existing PR is updated.
repo (all)
Importing new projects to Snyk
Used to present a list of all the available repos in the GitHub org in the Add Projects screen (import popup).
admin:read:org, repo (all)
Snyk tests on pull requests - initial configuration
Used to add SCM webhooks to the imported repos. Snyk uses these webhooks to:
  • Track the state of Snyk pull requests when PRs are created, updated triggered, merged, and so on.
  • Send push events to trigger PR checks.
admin:repo_hooks (read & write)
In non-brokered GitHub integrations, operations that are triggered via the Snyk Web UI, for example, opening a Fix PR or re-testing a Project, are performed on behalf of the acting user.
Therefore, a user who wants to perform this operation on GitHub via the Snyk UI must connect their GitHub account to Snyk with the required permission scope for the repositories where they want to perform these operations. See the Required permissions scope for repositories section for details.
Operations that are not triggered via the Snyk Web UI, such as daily and weekly tests and automatic PRs (fix and upgrade), are performed on behalf of random Snyk Organization members who have connected their GitHub accounts to Snyk and have the required permission scope for the repository.
For public repositories that are non-brokered, some operations, such as creating the PR, may occasionally be performed by [email protected].
Note that Snyk will continue to use a random Snyk Organization member's GitHub account to perform all the other operations. Therefore using this feature does not eliminate the need to connect users' GitHub accounts to Snyk.

Required permission scope for repositories

For Snyk to perform the required operation on monitored repositories, that is, reading manifest files on a frequent basis and opening fix or upgrade PRs, the accounts that are connected to Snyk, either directly or via Snyk Broker, must have the following access to the repositories:
Action
Purpose
Required permissions on the repository
Daily / weekly tests
Used to read manifest files in private repos.
Read or higher
Snyk tests on pull requests
Used to send pull request status checks whenever a new PR is created or an existing PR is updated.
Write or higher
Opening fix and upgrade pull requests
Used to create fix and upgrade PRs in the monitored repos.
Write or higher
Snyk tests on pull requests - initial configuration
Used to add SCM webhooks to the imported repos. Snyk uses these webhooks to:
  • Track the state of Snyk pull requests (when PRs are created, updated triggered, merged, and so on).
  • Send push events to trigger PR checks.
Admin

How to set up a GitHub account to open Snyk PRs

Snyk lets you designate a specific GitHub account to open fix and upgrade pull requests.
The configured account is only used for opening PRs. All other operations are still performed on behalf of a randomly-selected Snyk Organization member who has connected their GitHub accounts to Snyk.
To use this feature, follow these steps:
  1. 1.
    Go to the GitHub Integrations settings page in the Snyk Web UI via
    Settings
    Organization Settings > Integrations > Source control > GitHub.
  2. 2.
    In the Open Snyk automatic PRs from a fixed GitHub account section, enter your GitHub personal access token. You can generate this from your GitHub account.
  3. 3.
    Click Save to enable this feature.
Set an account to open Snyk PRs
Set an account to open Snyk PRs
Ensure that the GitHub account that you designate to open Snyk PRs has write-level permissions or higher for the repos you want to monitor with Snyk.
See repository permission levels on GitHub for more information.

How to assign pull requests to users

Feature availability
The Auto-assign PRs feature is supported only for private repositories.
Snyk can automatically assign the pull requests it creates to ensure that they are handled by the right team members.
Auto-assign for PRs can be enabled for the GitHub integration and all Projects imported via GitHub, or on a per-Project basis.
Users can either be manually specified, and all will be assigned, or automatically selected based on the last commit user account.

Enable Auto-assign for all Projects in the GitHub integration

To configure the Auto-assign settings for all the Projects from an imported private repository, go to the Github integration settings via
Settings
Organization Settings > Integrations > Source control > GitHub and select Enable pull request assignees.
You can then choose to assign PRs to the last user to change the manifest file or specified contributors.
Auto-assign PRs in private repos
Auto-assign PRs in private repos

Enable Auto-assign for a single Project

To configure the Auto-assign settings for a specific Project from an imported private repository, follow these steps:
  1. 1.
    In the Projects tab for your Organization, select and expand the relevant private repository, select a Target, and click the Settings cog.
    Settings cog for target settings
    The Project page opens.
  2. 2.
    On the Project page, apply unique settings for that specific Project. Select the Settings tab in the upper right and the Github integration __ option in the left sidebar.
  3. 3.
    Go to the Pull request assignees for private repos section at the bottom of the page and choose to Inherit from integration settings or Customize only for this Project.
  4. 4.
    Ensure Auto-assign PRs for this private Project is enabled.
  5. 5.
    Choose to assign PRs to the last user to change the manifest file or named contributors.
Auto-assign PRs for this private Project
Auto-assign PRs for this private Project

How to disable the Snyk GitHub integration

The Snyk GitHub SCM integration leverages the OAuth app integration. If you integrated GitHub without using Snyk Broker, you can disconnect it by following these steps:
  1. 1.
    In GitHub, log in to the GitHub account that you used to create the integration.
  2. 2.
    Go to your GitHub account settings and select the Applications option in the left sidebar.
  3. 3.
    Select the Authorized OAuth Apps tab. You can also reach the Authorized OAuth Apps tab directly.
  4. 4.
    Find the Snyk entry, click the three (3) dots on the right, and select Revoke.
Revoke OAuth authorization
Revoke OAuth authorization
Revoking this access effectively disconnects Snyk’s access to that GitHub account.
  • Existing imported snapshots will persist in Snyk and continue to be re-scanned based on the existing snapshots until deleted.
  • Snyk will no longer be able to import new Projects from the GitHub integration and will no longer re-scan on new code merges.
In addition, you must confirm that Snyk is not enabled on any existing Branch protection rules.
Note that branch protection is active only after a PR has been raised.
  1. 1.
    From the main page of your GitHub repository, go to Settings > Branches > Branch protection rules.
  2. 2.
    Ensure there are no Status checks found in the last week for this repository.
A disconnected GitHub integration will still appear as configured in the Integrations menu of the Snyk UI. However, clicking on the integration settings will show that it is not connected. In this case, the "configured" integration can safely be ignored.

GitHub badges

After you are vulnerability-free, you can put a badge on your README page to let the world know that your package has no known security holes. This shows your users that you care about security and tells them that they should care too.
The badge indicates the vulnerability state of the latest commit on the master branch.

Repository badges

To show a badge for a specific Node.js, Ruby, or Java GitHub repository, copy the relevant HTML or markdown snippet that follows and replace {username}/{repo} with the GitHub username and repo you want to test.

HTML for repository badge

<a href="https://snyk.io/test/github/{username}/{repo}">

Markdown for repository badge

[![Known Vulnerabilities](https://snyk.io/test/github/{username}/{repo}/badge.svg)](https://snyk.io/test/github/{username}/{repo})

Badges for a branch, release version, or other tag

To show the vulnerability state of a specific branch, release, or tag, add its name after the repo name in the URL.
For example, to show a badge for the 4.x branch of the express repo, you would use the URL: https://snyk.io/test/github/expressjs/express/4.x/badge.svg.

Badge results

  • A green badge indicates that there are no vulnerabilities.
    No vulnerabilities
  • A red badge indicates how many vulnerabilities were found.
    Number of vulnerabilities
  • A grey badge indicates that the repository has not been scanned.
    Unknown vulnerabilities

Badge styles

To change the style of the badge, you can add the following query parameters after badge.svg:
  • Flat rectangle with squared edges: ?style=flat-square
    Flat rectangle badge
  • "Plastic" rectangle with rounded edges and shading ?style=plastic
    "Plastic" rectangle badge

npm badges

To show a badge for a given npm package, copy the relevant snippet that follows, and replace {name} with the name of your package.

HTML for npm badge

<img src="https://snyk.io/test/npm/{name}/badge.svg" alt="Known Vulnerabilities" data-canonical-src="https://snyk.io/test/npm/{name}" style="max-width:100%;"/>

Markdown for npm badge

[![Known Vulnerabilities](https://snyk.io/test/npm/{name}/badge.svg)](https://snyk.io/test/npm/{name})
The badge shows the vulnerability state of the latest version of this package. To show the vulnerability state of a specific package, specify the version in the URL.
For example, to test version 1.2.3 of package name, you would use the URL: https://snyk.io/test/npm/name/1.2.3/badge.svg.

Badges for private packages and repos

Badges currently work only for public npm packages and GitHub repositories and fail if pointed at a private repository. To continuously watch for vulnerabilities in your GitHub repositories, both public and private, consider integrating them with Snyk.

Badges for custom manifest file locations

By default, the badge will test against the first valid manifest file it detects in the root of your Project.
If your manifest file is in a different location from the root of the repository, or if you have multiple manifest files for which you would like to show a badge, you can pass a target file query string parameter to direct the badge to test against another supported manifest file.

HTML for custom locations

<a href="https://snyk.io/test/github/{username}/{repo}">

Markdown for custom locations

[![Known Vulnerabilities](https://snyk.io/test/github/{username}/{repo}/badge.svg?targetFile={path-to-target-file})](https://snyk.io/test/github/{username}/{repo})