This repository is in maintenance mode, no new features are being developed. Bug & security fixes will continue to be delivered. Open source contributions are welcome for small features & fixes (no breaking changes)
Snyk helps you find, fix and monitor for known vulnerabilities in your dependencies, both on an ad hoc basis and as part of your CI (Build) system.
Snyk API project importer. This script is intended to help import projects into Snyk with a controlled pace utilizing available Snyk APIs.
What does it offer?
rate limiting handling- the script will pace requests to avoid rate limiting from Github/Gitlab/Bitbucket etc and to provide a stable import.queue- requests to Snyk are queued to reduce failures.retries- the script will kick off an import in batches, wait for completion and then keep going. Any failed requests will be retried before they are considered a failure and logged.
If you need to adjust concurrency you can stop the script, change the concurrency variable and start again. It will skip previous repos/targets that have been requested for import.
-
Utilities
- Creating orgs in Snyk
- Generating import data
- Mirroring Github.com/Github Enterprise organizations & repos in Snyk
- GitHub Cloud App Integration
- Mirroring Gitlab organizations & repos in Snyk
- Mirroring Bitbucket Server organizations & repos in Snyk
- Mirroring Bitbucket Cloud organizations & repos in Snyk
-
Sync: detecting changes in monitored repos and updating Snyk projects
-
Example workflows
snyk-api-import CLI can be installed through multiple channels.
Use GitHub Releases to download a standalone executable of Snyk CLI for your platform.
Install with npm or Yarn
Snyk snyk-api-import CLI is available as an npm package. If you have Node.js installed locally, you can install it by running:
npm install snyk-api-import@latest -gor if you are using Yarn:
yarn global add snyk-api-importBy default the import command will run if no command specified.
import- kick off a an API powered import of repos/targets into existing Snyk orgs defined in import configuration file. 100% support available for all project types supported via Import API.help- show help & all available commands and their optionsorgs:data- util generate data required to create Orgs via API.orgs:create- util to create the Orgs in Snyk based on data file generated withorgs:datacommand.import:data- util to generate data required to kick off an import.list:imported- util to generate data to help skip previously imported targets during import.
The logs can be explored using Bunyan CLI
The snyk-api-import tool now supports GitHub Cloud App authentication, providing enhanced security and functionality compared to traditional Personal Access Tokens.
- Enhanced Security: Uses GitHub App authentication with JWT tokens and installation tokens
- Higher Rate Limits: 5000 requests/hour per installation (vs per user)
- Granular Permissions: Repository access controlled at the GitHub App installation level
- Role-Based Access Control: Application-level permissions instead of user-level
- Go to your organization's GitHub settings
- Navigate to "Developer settings" → "GitHub Apps"
- Click "New GitHub App"
- Configure the following settings:
- App name: Choose a descriptive name (e.g., "Snyk Import Tool")
- Homepage URL: Your organization's website
- Webhook URL: Leave empty (not required for this integration)
- Repository permissions:
- Contents: Read
- Metadata: Read
- Pull requests: Read
- Issues: Read
- Organization permissions:
- Members: Read
- Subscribe to events: Leave empty (not required)
- After creating the app, install it on your target organization(s)
- Note the App ID from the app settings
- Generate a private key and download it (PEM format)
Set the following environment variables:
export GITHUB_APP_ID="your-app-id"
export GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
your-private-key-content-here
-----END RSA PRIVATE KEY-----"Optional: If you want to target a specific installation:
export GITHUB_APP_INSTALLATION_ID="your-installation-id"Use github-cloud-app as the source type in your commands:
# 1. Generate organization data
snyk-api-import orgs:data --source=github-cloud-app --groupId=your-group-id
# Optional: Use an existing Snyk organization as a template for settings
snyk-api-import orgs:data --source=github-cloud-app --groupId=your-group-id --sourceOrgPublicId=your-template-org-id
# 2. Create organizations in Snyk
snyk-api-import orgs:create --file=group-your-group-id-github-cloud-app-orgs.json
# 3. Set up GitHub Cloud App integration in each organization
# IMPORTANT: You must manually configure the GitHub Cloud App integration in each
# organization through the Snyk UI or API before proceeding to step 4.
# Go to each organization in Snyk and add the GitHub Cloud App integration.
# 4. Generate import targets
snyk-api-import import:data --source=github-cloud-app --orgsData=orgs-data.json
# 5. Sync projects
snyk-api-import sync --source=github-cloud-app --orgPublicId=your-org-id- Private Key Storage: Store the private key securely and never commit it to version control
- Token Rotation: GitHub App installation tokens are automatically rotated every hour
- Minimal Permissions: The app only requests read permissions for repository metadata and contents
- Organization Scope: Access is limited to organizations where the app is installed
-
"GITHUB_APP_ID environment variable is required"
- Ensure
GITHUB_APP_IDis set to your GitHub App's numeric ID
- Ensure
-
"GITHUB_APP_PRIVATE_KEY must be in PEM format"
- Ensure the private key includes the full PEM headers and is properly formatted
-
"Failed to authenticate with GitHub App"
- Verify the app is installed on the target organization
- Check that the private key matches the app
- Ensure the app has the required permissions
-
"No organizations found"
- Verify the app is installed on organizations (not just users)
- Check that the app has access to the repositories you want to import
-
"Missing integrationId in import targets"
- Ensure you have set up the GitHub Cloud App integration in each Snyk organization
- The integration must be configured through the Snyk UI before running
import:data - Check that the integration appears in the organization's integrations list
Run with debug logging to get more detailed error information:
DEBUG=snyk* snyk-api-import orgs:data --source=github-cloud-app --groupId=your-group-idWhat is the minimum version of Node that the tool supports?
Please check the .nvmrc file for the supported version of Node.
Error: ENFILE: file table overflow, open or Error: EMFILE, too many open files
If you see these errors then you may need to bump ulimit to allow more open file operations. In order to keep the operations more performant tool logs as soon as it is convenient rather than wait until very end of a loop and log a huge data structure. This means depending on number of concurrent imports set the tool may exceed the system default ulimit.
Some of these resources may help you bump the ulimit:
ERROR: HttpError: request to https://github.private.com failed, reason: self signed certificate in certificate chain
If your Github / Gitlab / Bitbucket / Azure is using a self signed certificate, you can configure snyk-api-import to use this certificate when calling the HTTPS APIs.
export NODE_EXTRA_CA_CERTS=./path-to-ca
Does this work with brokered integrations?
Yes. because we reuse the existing integration with your SCM (git) repository to perform the imports, the brokered connection will be used when configured.
What is supported for import command?
snyk-api-import supports 100% of the same integration types and project sources as the Import API documentation. If an example is not in the docs for your use case please see the API documentation