Snyk GitHub Enterprise integration
If you are a Snyk Enterprise plan customer, Snyk recommends that you use the GitHub Enterprise integration. If you use the self-hosted GitHub Enterprise product, you must use the Snyk GitHub Enterprise integration. See Using GitHub or GitHub Enterprise integration for details.
Feature availability GitHub Enterprise integration is available to Snyk Enterprise plan customers. If you have a Legacy Business plan, contact Snyk support for access. See the Plans and pricing page for details.
Prerequisites for Snyk GitHub Enterprise integration
Internet-accessible repositories. If your repositories are not internet-accessible, you must use Snyk Broker. This requires creating a startup script. For the script and instructions, see GitHub Enterprise - install and configure using Docker.
A public or private GitHub project.
You do not need to be on a GitHub Enterprise level plan to use the Snyk GitHub Enterprise integration.
Snyk GitHub Enterprise integration features
The Snyk GitHub Enterprise integration lets you:
Perform periodic security scans across all integrated repositories.
Detect vulnerabilities in your Open Source components.
Provide automated fixes and upgrades through status checks in GitHub.
How to set up the Snyk GitHub Enterprise integration
Follow these steps to connect Snyk with your GitHub repositories:
Create a dedicated service account in GitHub Enterprise with a write level or higher scope for the repos you want to monitor with Snyk permissions. See Types of GitHub accounts and Required access scopes for the GitHub integration for details. Note that to create webhooks, which is required for PR checks, the repo permission for the account must be
Admin
. GitHub custom roles are not supported.Generate a personal access token for that account.
How to generate a Personal Access Token
Generate a classic personal access token for the account with the following access scopes:
repo (all)
admin:read: org
admin:repo_hooks (read & write)
If you are using fine-grained personal access tokens, the following repository access scopes are required:
Administration: Read-only
Commit Status: Read and write
Content: Read and write
Metadata: Read-only
Pull requests: Read and write
Webhooks: Read and write
For fine-grained personal access tokens, an additional Members access: Read-only
organization access scope is required.
Create a personal access token in GitHub Enterprise under User settings > Developer settings.
The Snyk GitHub integration is bound to a single user, preferably a GitHub service account. The level of access for the integration is defined by the combination of the user's permissions in GitHub (see required access scopes) and the access defined for the PAT on that user's account. If the PAT is defined with more permission than the user's GitHub account, the integration will not be able to use that permission.
Why does Snyk require fine-grained access tokens to have pull request: read/write
and content: read/write
scopes? Does this mean Snyk can write code to our repos?
Snyk uses PRs to tell GitHub Enterprise that a merge is to occur. To do this, change content is pushed into a branch, which requires the content: write
scope. A separate call is then made to create the fix PR, which requires the pull request: write
scope. GitHub Enterprise is then instructed to create a PR, merging the change branch into the default branch.
How to authorize your Personal Access Token and enable SSO
In Snyk, navigate to the Integrations page and click the GitHub Enterprise card.
Enter your GitHub Enterprise URL and the personal access token (PAT) for the service account you created, and Save your changes. After Snyk has successfully connected to the GitHub instance, the list of available repositories displays for your selection.
If your GitHub Enterprise organization enforces SAML/SSO, select Configure SSO next to the PAT in GitHub after the PAT has been created. Occasionally, SSO is enforced in your GitHub Enterprise organizations after a PAT and Integration are configured. If this happens, any Projects that have already been imported show in Snyk, but retests, PR Checks, and so on, will not be performed. To fix this, check the Configure SSO settings to ensure the GitHub Enterprise organization is Authorized. If the organization is showing as Authorized, but the issue still persists, try de-authorizing the organization and then re-authorizing.
To use the integration with GitHub Enterprise Cloud, add the URL https://api.github.com
. To integrate with a self-hosted GitHub Enterprise, add the URL https://your.github-enterprise.host
in step two of PAT authorization.
Ensure that there are no trailing characters such as /
following the url. An integration with trailing characters in the URL may connect successfully but provide incorrect links back to the GitHub files.
If the PAT token changes or expires in GitHub, the integration with Snyk will not function. To resolve this, update the token in the Snyk GitHub Enterprise Integration settings.
How to import GitHub repositories
Select the repositories you want to import to Snyk and click Add selected repositories.
Snyk starts scanning the selected repositories for dependency files, such as package.json
, in the entire directory tree and imports the repositories to Snyk as Projects.
The imported Projects appear on your Projects page and are continuously checked for vulnerabilities.
Uses of the Snyk GitHub Enterprise integration
Obtain Project-level security reports
Snyk produces advanced security reports, allowing you to explore the vulnerabilities found in your repositories and fix them by opening a fix pull request directly to your repository with the required upgrades or patches.
The example that follows shows a Project-level security report.
Monitor Projects and generate automatic fix pull requests
Snyk scans your Projects on either a daily or a weekly basis. When new vulnerabilities are found, Snyk notifies you by email and opens an automated pull request with fixes for your repositories.
The example that follows shows a fix pull request opened by Snyk.
To review and update the automatic fix pull request settings:
In Snyk, navigate to Settings > Integrations > Source control > GitHub Enterprise > Edit Settings.
Scroll to the Automatic fix pull requests section, then select options as required:
Test new pull requests
The PR Checks feature enables Snyk to test any newly-created pull requests in your repositories for security vulnerabilities and sends a status check to GitHub. This allows you to see, directly from GitHub, whether the pull request introduces new security issues.
The following example shows how Snyk pull request checks appear on the pull requests page in GitHub.
To review and adjust the pull request test settings: In Snyk, navigate to Organization Settings > Integrations > Source control > GitHub Enterprise, and select Edit Settings.
Scroll to Snyk PR status checks; see Configure PR Checks for details.
How to disconnect the Snyk GitHub Enterprise integration
Disconnecting the Snyk GitHub Enterprise integration halts all scans for imported repositories, PR checks cannot be executed, and Projects are deactivated in the Snyk Web UI.
Navigate to the Snyk GitHub Enterprise integration Settings.
At the bottom of the page, select Remove GitHub Enterprise.
A confirmation screen opens. To proceed, select Disconnect GitHub Enterprise.
After GitHub Enterprise is disconnected, imported Snyk Projects will be set to inactive, and you will no longer get alerts, pull requests, or Snyk tests on pull requests.
You can re-connect anytime; however, re-initiating GitHub Enterprise projects for monitoring requires setting up the integration again.
Required access scopes for Snyk GitHub Enterprise integration
All the operations, whether triggered manually or automatically, are performed for a GitHub service account that has its token configured on the integrations settings page. This shows the required access scopes for the configured token. GitHub custom roles are not supported :
Last updated