Snyk SCM Integrations
You can integrate Snyk with your Git repository to quickly and easily gain visibility across all the Snyk Projects that you add to your Projects list.
This page contains information about the following Snyk SCM integration aspects:
Overview
When you want to add new integrations to your Snyk account you must first decide the level type at which you want to install the integration. Snyk supports different SCM integrations on different levels of the Snyk hierarchy:
Group level - Group level integrations only support Snyk AppRisk Essentials or Snyk AppRisk Pro.
Organization level - Organization level integrations support all other Snyk products. Snyk does not support Snyk AppRisk Essentials or Snyk AppRisk Pro integrations at the Organization level.
If you added the GitHub integration at Organizational and/or Group levels and you have configured SAML SSO for it, then you must authorize your GitHub PAT. Navigate to the How to authorize your Personal Access Token and enable SSO page for more details.
Group level - Snyk AppRisk SCM integrations
At the Group level, you can set up and customize your Snyk AppRisk integrations from the Integrations Hub where the following SCMs are available:
Snyk AppRisk Group-level SCM integrations provide broader visibility into all the application assets for a given customer and pull in the additional application context and, or metadata, for example, information on developers, commits, and so on.
If your SCM instance is not publicly accessible, you must connect using Snyk Broker. For details, see Snyk Broker - AppRisk.
The Integrations page at the Group level shows all active integrations, including any data automatically synced from your existing Snyk Organizations, and provides access to the Integration Hub.
The SCM integrations use an incremental approach to retrieve repositories. This means that when a sync is initiated, it checks the last update time of the repository and only transfers the repositories that have been modified since then.
If there have been changes to the scope of the user or PAT used for the integration, any repositories that are newly within scope will only be identified after either a change to trigger the incremental collection or a change to the integration configuration itself.
The following supported Snyk data are automatically synced:
Snyk Open Source
Snyk Code
Snyk IaC
Snyk Container
Each connected integration enables you to:
Pause data syncing
Modify integration profiles and configurations
Delete the integration
Check when the integration was last synced and when the next sync is scheduled.
Wildcard SCM integration
The wildcard integration allows you to use a special character to detect and integrate multiple SCM organizations simultaneously.
The wildcard integration applies to the GitHub and Azure DevOps integrations and offers support when you set them up using Snyk Broker.
You can use the wildcards while setting up your integration using the Integration Hub:
Open the Integration Hub menu.
Select the SCM tag and search for GitHub or Azure DevOps.
Click the Add button.
In the Organizations field, add the Organization details by using the
*
symbol. For example, using*snyk
integrates all SCM Organizations that have Snyk in their name.All the Organizations that match with the wildcard,
*
symbol will be added.
The wildcard, *
symbol is considered a living command and will be applied every time you are rescanning your repositories.
Snyk AppRisk integrations ecosystem
You can refer to the table below to verify the availability and compatibility of all integrations for Snyk AppRisk. The integrations are categorized by type, listed by name, and indicated as available or not for both Snyk AppRisk Essentials and Snyk AppRisk Pro.
Dev portals and Service catalogs
✔️
✔️
Using the Integration Hub
Use the Integration Hub page to onboard integrations and populate Snyk AppRisk with data from SCM tools.
See the Snyk Web UI page for step-by-step instructions on how to set up an integration.
After the integration is validated, a card is displayed on the Integrations page, allowing you to enable or disable the connection, edit the settings, or remove the connection from your configuration.
If you modify the permissions and scopes after the initial configuration, it is essential to either initiate an import or implement a change within the repository. This action allows Snyk to acknowledge and incorporate the updates effectively.
Using Snyk Broker
If your SCM instance is not publicly accessible, you need Snyk Broker. You can install and configure your Snyk Broker using Docker or Helm. For more information about Snyk Broker, see the Snyk Broker documentation, including Snyk Broker - AppRisk.
Enable the Snyk AppRisk flag in your Snyk Broker deployment environment before running the commands.
You can find on GitHub all the updated .json
files that include the allowed list of accessible endpoints for the integrations.
Organization level - Snyk SCM integrations
Snyk provides seamless integrations with various source control management systems such as GitHub, GitLab, Bitbucket, and Azure Repos at the Organizational level. These integrations enable you to automatically scan for vulnerabilities and receive actionable insights to enhance the security of your repositories. By integrating at this level, you can ensure comprehensive protection for all your Projects within the Organization.
Snyk Source Control Manager (SCM) integrations allow you to:
Continuously perform security scanning across all integrated repositories
Detect vulnerabilities in your open-source components
Provide automated fixes
Snyk can integrate with the following SCMs to help you track, monitor, and fix the issues and vulnerabilities in your code:
Workspaces for SCM integrations
This feature is available for GitHub, GitHub Enterprise, GitHub Cloud App, GitLab, Bitbucket Server, Bitbucket Cloud App, Bitbucket Cloud (Legacy), and Azure Repos (TFS) integrations.
The Workspaces feature enables Snyk to ingest a temporary snapshot of repository contents, and all commit metadata through your configured SCM integrations.
For detailed information on this feature, including enablement steps, see Workspaces for SCM integrations.
Deployment order recommendations
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.
To ensure a smooth rollout of Snyk across your organization, Snyk provides a suggested deployment timeline consisting of deployment stages, configuration steps, and the desired outcome for each stage.
For detailed steps, see Deployment recommendations for SCM integrations.
User permissions and access scope requirements
Snyk SCM integrations may require different permission requirements based on the connection method.
See the following for detailed permission requirements:
GitHub and GitHub Enterprise permissions requirements
For information about token permissions in a brokered integration, see GitHub - prerequisites and steps to install and configure Broker and Integrated SCM tokens for Snyk Broker.
The Snyk GitHub Enterprise 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 and the access defined for the Personal Access Token (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.
The following table details the access scopes required in GitHub and GitHub Enterprise for Personal Access Tokens (PAT) and the scopes required for Snyk to perform the required operations on monitored repositories, such as reading manifest files on a frequent basis and opening fix or upgrade PRs. GitHub custom roles are not supported.
Daily/weekly tests: Read manifest files in private repositories.
repo (all)
≥ read
Manual fix pull requests: Create fix PRs in monitored repositories.
repo (all)
Automatic fix and upgrade pull requests: Create fix or upgrade PRs in monitored repositories.
repo (all)
≥ write
Snyk tests on pull requests: Send PR status checks whenever a new PR is created, or an existing PR is updated.
repo (all)
≥ write
Initial configuration of Snyk tests on pull requests: Used to add SCM webhooks to the imported repo
admin:repo_hooks (read & write)
admin
Import new Projects to Snyk: Present a list of all the available repos in the GitHub org in the Add Projects screen.
admin:read:org
repo (all)
A fine-grained PAT requires additional repository access scopes:
Administration: Read-only
Commit Status: Read and write
Content: Read and write
Metadata: Read-only
Pull requests: Read and write
Webhooks: Read and write
Members access: Read-only (Organization access scope)
The Administration: Read-only
permission on the PAT is crucial for Snyk to identify and list the user's accessible GitHub organizations, a prerequisite for importing a new Project.
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.
Snyk uses SCM 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.
GitHub Cloud App permission requirements
The Snyk GitHub Cloud App integration uses role-based access control, meaning access control is not dependent on individual users or their role, it is instead tied to the app entity.
To set up the GitHub Cloud app integration you must be a:
Snyk Organization Admin.
GitHub Organization Admin.
GitHub Repository Admin (if installing through the GitHub UI).
While some permissions may be optional from GitHub’s perspective, they are necessary to support Snyk functions. These permissions cannot be customized for your individual needs because the app is registered under the Snyk Organization.
The following table states the required GitHub App permissions and scopes:
Determine if the GitHub user has admin role on the GitHub org, to restrict app installation reuse to only admin users
Members
Organization
Read
Search repositories, and access repository metadata.
Metadata
Repository
Read
Interact with the GitHub Checks tab
Checks
Repository
Read and write
Create commits and branches
Contents
Repository
Read and write
Send PR check results as commit statuses
Commit status
Repository
Read and write
Get pull requests details, post related comments (next gen PR experience)
Pull request
Repository
Read and write
Manage webhooks which trigger the PR checks
Repository hooks
Repository
Read and write
GitHub Server App permission requirements
To set up the GitHub Server App you must be a:
Snyk Organization Admin.
GitHub Organization Admin.
You must have a public or private GitHub repository.
GitHub Server App for Universal Broker permission requirements
To set up the GitHub Server App for Universal Broker you must be a:
Snyk Organization Admin.
GitHub Organization Admin.
You must have a self-hosted instance of GitHub.
GitLab permission requirements
The Snyk GitLab integration uses either a personal access token (PAT) or group access token (GAT), depending on the GitLab account tier you are on.
To set up the Snyk GitLab integration you must be a:
Snyk Group or Organization Admin.
GitLab Owner or Maintainer
A PAT is used for managing personal GitLab projects and requires the api
scope. For AppRisk to show all repositories from GitLab, the user generating the PAT should be part of the GitLab group where their GitLab permissions can be a minimum of Guest.
A GAT is used for managing multiple GitLab projects in a GitLab group and requires the api
scope and maintainer role selected from the dropdown. You must be a GitLab Premium or Ultimate account tier holder to create a GAT.
Bitbucket permission requirements
The Snyk Bitbucket integrations use different access control mechanisms to connect with Snyk:
Snyk Bitbucket Cloud requires the creation of an app password.
Snyk Bitbucket Cloud App requires Bitbucket workspace authorization and related permissions.
Snyk Bitbucket Data Center/Server requires a dedicated username and password or a personal access token (PAT).
To set up any Snyk Bitbucket integration, you must be a Bitbucket Workspace Admin.
Bitbucket Cloud and Bitbucket Data Center/Server scopes
The following table details the required permission scopes in Bitbucket Cloud and Bitbucket Data Center/Server:
Daily / weekly tests: Read manifest files in private repos.
Repositories: read
≥ write
Manual fix pull requests (triggered by the user): Create fix PRs in repos.
Repositories: read, write
Pull Requests: read, write
Automatic fix and upgrade pull requests: Create fix/upgrade PRs in repos.
Repositories: read, write
Pull requests: read, write
≥ write
Snyk tests on pull requests: Send PR status checks when a new PR is created or a PR is updated.
Repositories: read, write
Pull requests: read, write
≥ write
Snyk tests on pull requests (initial configuration): Add SCM webhooks to imported repos.
Webhooks: read, write
admin
Importing new projects to Snyk: Lists available repos in the Bitbucket instance in the Add Projects screen.
Account: read
Workspace membership: read
Projects: read
Snyk uses SCM webhooks in Bitbucket to:
Track the state of pull requests when PRs are created, updated triggered, merged, and so on.
Send push events to trigger PR checks.
Bitbucket Cloud App scopes
The following table details the permissions required for the Bitbucket Cloud App:
Daily / weekly tests
Used to read manifest files in private repositories.
Read and modify your repositories and their pull requests
Snyk tests on pull requests
Used to send pull request status checks when a new PR is created, or an existing PR is updated.
Read and modify your repositories and their pull requests
Opening fix and upgrade pull requests
Used to create fix PRs in monitored repositories.
Read and modify your repositories and their pull requests
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.
Read and modify your repositories' webhooks
Azure Repositories (TFS) permission requirements
The Snyk Azure Repositories (TFS) integration uses an Azure DevOps personal access token (PAT). This token is configured with the specific permissions Snyk needs to access your Azure repositories.
To set up the Snyk Azure Repositories (TFS) integration you must be:
A member of the Project Administrators group in Azure. This ensures the PAT has the
edit subscriptions permissions
required to enable webhooks.
In Azure, the PAT requires the following permissions for Snyk access:
Expiry: Custom defined. Snyk recommends choosing a token expiration date that is far in the future.
Scopes: Custom defined.
Read & write
permissions are needed for the Code scope.
Integrated SCM tokens for Snyk Broker
An integrated SCM token is required for Broker client setup. It is used in the -e <SCM>_TOKEN
parameter, for example, -e GITHUB_TOKEN=xxx…
, to enable access to the SCM. These meet certain permissions needed for the operation of Broker and Snyk Code.
An integrated SCM token can be generated for the following SCM integrations:
GitHub and GitHub Enterprise SCM token
Format: GITHUB_TOKEN=
- a GitHub personal access token.
Scopes: repo, read:org
and admin:repo_hook.
GitLab SCM token
Format: GITLAB_TOKEN=
- a GitLab personal access token.
Scopes: api
.
GitLab account with Maintainer
permission.
Azure Repositories (TFS) SCM token
Format: AZURE_REPOS_TOKEN=
- an Azure Repos personal access token.
Scopes: Custom defined
, Code:
Read & write
.
Bitbucket Server/Data Center SCM token
Format: BITBUCKET_USERNAME=
, BITBUCKET_PASSWORD=
– the Bitbucket Server username and password or a Bitbucket Server personal access token.
Scope: Repository admin
.
Last updated