Snyk has introduced a new integration for GitHub, integrating Snyk as a GitHub application.

Legacy & current customers who are utilizing the GitHub (OAuth) and GitHub Enterprise (personal access token - PAT) integrations can migrate to the new integration without losing report trending or ignores by utilizing a tool provided by Snyk. This tool is covered later in the Migration step of this lesson.

The Snyk GitHub Cloud App improves on many features as compared to the current GitHub integration, including role-based, granular access control, increased API rate limits, and creation of an entry point for expanded and enhanced developer experiences for the future.

More information on this integration can be found within Snyk documentation.

Requirements

The user must have

1. Snyk organization administrator role
2. GitHub organization administrator user role
3. Public or private GitHub repository

Additional Notes

• This integration works with GitHub or GitHub Enterprise. On-Prem GitHub and Broker are not currently supported. Please note Github Server app is currently in Beta.
• If you are an existing Snyk customer using the legacy GitHub or GitHub Enterprise integration cards in Snyk with the GitHub Cloud instances (and not on-prem), this module will have an extra step for you to migrate data
• The migration script requires you to specify an option explicitly if using the GitHub integration card in Snyk. More on this later.
• Asset and Inventory analysis integrations (AppRisk) are configured at the Group level. At this time it requires you to choose GitHub and specify a PAT token.

Complete the following steps to integrate Snyk with GitHub using the Snyk GitHub Cloud integration.

• Navigate to the relevant organization(s)
• Click Integrations on the main menu
• Select GitHub Cloud App

• Click Authorize on the appropriate organizations
• Click Continue when prompted

• Click Authorize Snyk.io

• Select the arrow next to the new organization you wish to configure, or to configure settings for an existing organization
• If the GitHub Cloud App is already installed in a GitHub organization, you can select that same GitHub organization during the integration process for a different Snyk Organization. See documentation for more information

• When prompted, install and authorize, optionally selecting all or specific repositories
• When prompted, provide GitHub credentials

• Configure your integration settings
• For more information on common integration settings, and rollout methodologies, see the Team and Enterprise implementation guides
• If you are migrating from the GitHub or GitHub Enterprise integrations, please visit the next section, otherwise navigate directly to the Validating the Integration step of this lesson

If you are currently using one of the Snyk GitHub or Snyk GitHub Enterprise integrations, and wish to migrate to the Snyk GitHub Cloud App integration, complete the following steps and review the additional examples before executing the final migration commands. If you are not migrating, skip the migration content by scrolling down to the Validating the Integration section to continue.

Task 1 - Collect required authorization tokens

Utilize one of the following Snyk token strategies

1. Navigate to the group level and use a group level service account token. This strategy may be preferred if performing this on a lot of organizations.
2. Use a service account token at the organization level, in which case one is needed per organization
3. Use a personal API token found under your personal profile in Snyk

Task 2 - Identify Target Organizations

For each of the organizations you want to create or migrate to the Github Cloud App integration, you will need to retrieve an ID for scripting purposes

Under Settings of each organization, retrieve each organization ID

• Alternatively, utilize REST APIs such as https://api.snyk.io/rest/orgs

Task 3 - Download Migration Tool

Download this tool , which migrates history and ignore data from your prior GitHub integrations to the newly created projects. The Readme contains install instructions. Be sure to review the following pages before executing this script!

The Readme contains install instructions for different scenarios, however a common path is shown below

1. Install Python >=3.11, if not already installed
2. Install Poetry using the command

3. Download or clone https://github.com/snyk-labs/snyk-migrate-to-github-app
4. In a terminal, from within that directory, execute the install, followed by the command to display help. Type the following commands next to the $ prompts:

Task 4 - Review the following considerations to determine commands to use

Review the following options to determine applicability to your use case

a) Test runs

Prior to running the full command in the following section, you can perform a dry run to see how many project targets would be impacted.

Add --dry-run to your command. The output will list the targets and provide a count. As this is recommended practice, dry run commands will be included in the later examples prior to execution.

b) Regional considerations

If using an instance different from snyk.io, such as the EU or AU tenant, you will utilize the steps specified in the README for this tool with respect to each region.

For example when the script is run in the final step, it might add a tenant attribute like below.

c) Integration type considerations

This is an important attribute if you are a Snyk “GitHub” integration user. Prior to starting, note that this tool defaults and assumes Snyk’s GitHub Enterprise integration is the integration being migrated.

• If you are using Snyk’s GitHub integration, as pictured above, you must add --include-github-targets, as discussed in the following section
• If you see zero targets listed when running the --dry-run command, it’s likely related to this option if access and permissions are correct.

Task 5 - Migrate Data - Test & Execute

Prior to executing these commands, please read the examples in the next section to review common options:

General Format (Snyk.io)

Snyk GitHub Enterprise migration command (replace placeholders using data from steps 1 & 2)

Snyk GitHub migration command (replace placeholders using data from steps 1 & 2)

Output

A list of targets will be shown, followed by completion message Saving session...

The following examples include options from the most common scenarios. Review the complete README for more options. Organization and Snyk tokens are represented here by 1234-5678-1234-4545 and abcd-1234-5678. Use your values instead when running these commands

Example 1 - Snyk.io GitHub Enterprise Migration

A typical Github Enterprise dry run call may look like this if these were your IDs & tokens:

Followed by the actual execution:

Example 2 - Snyk.io GitHub Migration

A typical GitHub Enterprise call may look like this if these were your IDs & tokens

Followed by the actual execution

Example3 - GitHub Enterprise EU instance

A typical GitHub Enterprise EU instance call may look like this if these were your IDs & tokens

Followed by the actual execution

Example 4 - GitHub Enterprise AU instance

A typical GitHub Enterprise call may look like this if these were your IDs & tokens:

Followed by the actual execution:

• Navigate to the Projects page within your Organization and import some projects, which will begin testing. If the import was successful, your integration is complete and you can begin onboarding your projects or further configure the integration using Settings->Integrations.

If this is your first integration with GitHub, scroll to the end of the lesson and close it to be marked completed. Otherwise, if you are migrating from an earlier GitHub integration, follow the additional steps below.

Validate migrating from GitHub/GitHub Enterprise Integration is complete

• On the Projects page, within a migrated organization, filter on GitHub Cloud App, removing the checks from the previous integrations, confirming only the GitHub Cloud App projects are appearing and none for the legacy integration. Similarly view the history and ignores for your projects.

Validation Examples

The screenshots below illustrate filtering to GitHub Cloud app with projects being displayed, followed by filtering with GitHub only, which was migrated from, where no projects exist. If you are migrating from Snyk's GitHub Enterprise integration, your second example would utilize that option.

Having similar results to the following demonstrates that the integration & migration were successful