GitHub Enterprise Server Integration

Setting up a GitHub Enterprise Server Integration

1. Create a dedicated service account in GitHub Enterprise, with write level or above permissions, to the repos you want to monitor with Snyk permissions. See Required permissions scope for the GitHub integration for details.

2. Generate a personal access token for that account, with repo (all), admin:read:org  and admin:repo_hooks (read & write) permissions scope. See GitHub Enterprise documentation for details.

3. Go to the Integrations page in Snyk and click on GitHub Enterprise Server:

4. Enter your Github Enterprise Server URL, and the personal access token for the service account you created:

5. Click Save.
   Snyk connects to your GitHub Enterprise Server instance. When the connection succeeds, the following indications appear:
   

6. Select the repos to import to Snyk, then click Add selected repositories.

7. Snyk starts scanning the selected repos for dependency files (such as package.json) in the entire directory tree and imports them to Snyk as projects:
   
   

8. The imported projects appear in your Projects page and are continuously checked for vulnerabilities.

GitHub Enterprise Integration Features

After the integration is set up, you can use the following capabilities:

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.

This is an example of a project level security report:

Projects monitoring and automatic fix pull requests

Snyk frequently scans your projects on either a daily or a weekly basis. When new vulnerabilities are found, it notifies you by email and by opening an automated pull requests with fixes to repositories. 

This is an example of a fix pull request opened by Snyk:

To review and adjust the automatic fix pull request settings, navigate to the GitHub Enterprise Integration Settings page in Snyk (Settings > Integration > GitHub Enterprise Server): 

Pull request testing

Snyk tests any newly created pull request in your repositories for security vulnerabilities, and sends a status check to GitHub Enterprise. This allows you to see whether the pull request introduces new security issues, directly from GitHub Enterprise.

This is how Snyk pull request checks appear in the Pull Request page in GitHub Enterprise:

To review and adjust the pull request tests settings, navigate to the GitHub Enterprise Integration Settings page in Snyk (Settings > Integration > GitHub Enterprise Server):

Required permissions scope for the GitHub integration

All the operations, triggered manually or automatically, are performed for a GitHub service account that has its token is configured in the integrations settings. This shows the required access scopes for the configured token: 

Action	Why?	Required permissions in GitHub
Daily / weekly tests	For reading manifest files in private repos	repo (all)
Manual fix pull requests (triggered by the user)	For creating fix PRs in the monitored repos	repo (all)
Automatic fix and upgrade pull requests	For creating fix / upgrade PRs in the monitored repos	repo (all)
Snyk tests on pull requests	For sending pull request status checks whenever a new PR is created / an existing PR is updated	repo (all)
Importing new projects to Snyk	For presenting 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	For adding Snyk's webhooks to the imported repos, so Snyk will be informed whenever pull requests are created or updated and be able to trigger scans	admin:repo_hooks (read & write)

 

Required permissions scope for repositories

For Snyk to perform the required operation on monitor repositories, such as reading manifest files on a frequent basis, the accounts connected to Snyk (either directly or using Snyk Broker) need the following access on the repositories:

Action	Why?	Required permissions on the repository
Daily / weekly tests	For reading manifest files in private repos	Write or above
Snyk tests on pull requests	For sending pull request status checks whenever a new PR is created / an existing PR is updated
Opening fix and upgrade pull requests	For creating fix / upgrade PRs in the monitored repos
Snyk tests on pull requests - initial configuration	For adding Snyk's webhooks to the imported repos, so Snyk will be informed whenever pull requests are created or updated and be able to trigger scans	Admin