Links

GitHub integration

Snyk's GitHub integration lets you:
  • Continuously perform security scanning across all the integrated repositories
  • Detect vulnerabilities in your open source components
  • Provide automated fixes and upgrades

About Snyk integration settings for GitHub

The GitHub integration works per user account and not per Snyk Organization. Each person in the Organization sets up the integration and their own unique integration settings: there are no shared Organization level settings for the GitHub integration.
Setting up this integration means it will be used for all the Snyk Organizations associated with your user __ account.
When you import a Snyk Project via your GitHub integration with the Snyk PR functionality enabled, Snyk PRs are created for that project. Similarly, if another person imports Projects with their GitHub integration after disabling the Snyk PR functionality, Snyk PRs are not created for the Projects they import.
You cannot use a GitHub integration to import public and private Projects via the Snyk API with a Snyk Service Account. This functionality is not available because the GitHub integration is associated with your user account and not with the Snyk Organization. To import public and private Projects via the API with a Snyk Service Account, use the GitHub Enterprise integration.

Setting up a GitHub Integration

The process to connect Snyk with your GitHub repositories includes the following steps:
  1. 1.
    In Snyk, go to Integrations > GitHub.
  2. 2.
    Choose whether you'd like to give Snyk access to both public and private repositories or only to public repositories. The GitHub authorization screen opens.
  3. 3.
    In the GitHub authorization screen, click Authorize Snyk to provide Snyk with access to your repositories.
  4. 4.
    Select the repositories you want to import to Snyk and click Add selected repositories (upper right corner of the page).
After you add them, Snyk scans the selected repositories for dependency files in the entire directory tree, (that is, package.json, pom.xml, and so on) and imports them to Snyk as projects.
The imported projects appear on your Projects page and are continuously checked for vulnerabilities.

GitHub integration features

Once the integration is in place, you'll be able to use capabilities such as:

Project level security reports

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.
Feature availability Reports are available with the Business and Enterprise plans. See the plans and pricing page for details.
The example below presents a 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 below presents a 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
(Organization Settings) > Integrations > Source control > GitHub.

Commit Signing

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.
Feature availability
This feature is not supported for brokered GitHub integrations.

Pull request testing

Snyk tests any newly created pull request in your repositories for security vulnerabilities and sends a status check to GitHub. This lets you see whether the pull request introduces new security issues, directly in GitHub.
The example below presents how Snyk pull request checks appear on the GitHub Pull Request page.
You can review and adjust the pull request tests settings via the Snyk GitHub Integration settings page in
(Organization Settings) > Integrations > Source control > GitHub.

Required permissions scope for the GitHub integration

If you're on a Snyk Enterprise plan, you can use the open source Snyk Broker tool to act as a proxy between Snyk and your Source Code Management (SCM) system on-premise platforms, including Snyk Code Support, or your publicly-accessible Git-based repositories.
Snyk Broker lets you view and control Snyk activity in those repositories for increased data security.

Brokered GitHub Integrations

All the operations, both those that are triggered via the Snyk Web UI and the automatic operations, are performed for a GitHub service account that has its token configured with the Broker.
The table below presents a summary of the required access scopes for the configured token.
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)

Non-Brokered GitHub Integrations

  1. 1.
    Operations that are triggered via the Snyk Web UI (for example, opening a Fix PR or retesting 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, and have the required permissions scope for the repositories they want to perform these operations for. See the Required permissions scope for repositories section for more details.
  2. 2.
    Operations that are not triggered via the Snyk Web UI, such as daily / 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.
  3. 3.
    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 be able to perform the required operation on monitor 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) require 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 / an existing PR is updated
Write or higher
Opening fix and upgrade pull requests
Used to create fix / 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

1. Setting an account to open Snyk PRs

Snyk lets you designate a specific GitHub account to open fix and upgrade pull requests.
Note that the configured account is only used for opening PRs. All the other operations are still performed on behalf of a random Snyk organization member who has connected their GitHub accounts to Snyk.
To use this feature, follow the steps below:
  1. 1.
    Go to the GitHub Integrations settings page in the Snyk Web UI, via
    (Organization Settings) > Integrations > Source control > GitHub.
  2. 2.
    In the Set an account to open Snyk PRs section, set the toggle to Enabled.
  3. 3.
    In the right side of the section, follow the instructions to Create a personal access token in GitHub.
  4. 4.
    In the Personal access token field, paste the newly generated token to Snyk so it can be used to perform operations on GitHub (that is, opening Fix PRs, and so on).
Make sure that the GitHub account that you designate to open Snyk PRs has at least write level permissions (or higher) for the repos you want to monitor with Snyk.
See repository permission levels on GitHub for more information.

2. Assigning pull requests to users

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.
Feature availability
The Auto-assign PRs feature is only supported for private repositories.
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
(Organization Settings) > Integrations > Source control > GitHub, and configure the following options:

Enable Auto-assign for a single project in the Github integration

To configure the Auto-assign settings for a specific project from an imported private repository**:**
  1. 1.
    In the Projects tab for your organization, select and expand the relevant private repository, select a target, and click the Settings cog.
    The project page opens.
  2. 2.
    In the project page, to 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 select, customize, and confirm the relevant options in the sections:

Disconnecting the GitHub integration

Snyk’s GitHub SCM integration leverages the oAuth app integration. If you integrated GitHub without using the 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 3 dots on the right, and select Revoke.
Revoking this access effectively disconnects Snyk’s access to that GitHub account. Existing imported snapshots will persist in Snyk and continue to rescan 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.
Additionally, you must confirm that Snyk is not enabled on any existing Branch protection rules: From the main page of your GitHub repository, go to Settings > Branches > Branch protection rules, and make sure there are no Status checks found in the last week for this repository.

GitHub badges

Once you’re 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 below and replace {username}/{repo} with the GitHub username and repo you want to test.
HTML
<a href="https://snyk.io/test/github/{username}/{repo}">
Markdown
[![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.
  • A red badge indicates how many vulnerabilities were found.
  • A grey badge indicates that the repository has not been scanned.

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
  • "Plastic" rectangle with rounded edges and shading ?style=plastic

npm badges

To show a badge for a given npm package, copy the relevant snippet below, and replace {name} with the name of your package.
HTML
<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
[![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, you can 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 only work for public npm packages and GitHub repositories, and will 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 different location than the root of the repository, or if you have multiple manifest files that you would like to show a badge for, you can pass a targetFile query string parameter to direct the badge to test against another supported manifest file.
HTML
<a href="https://snyk.io/test/github/{username}/{repo}">
Markdown
[![Known Vulnerabilities](https://snyk.io/test/github/{username}/{repo}/badge.svg?targetFile={path-to-target-file})](https://snyk.io/test/github/{username}/{repo})