GITBOOK-7375: NE - Migrate Bitbucket Cloud PAT: page merge

docs/SUMMARY.md

@@ -245,7 +245,7 @@
     * [Snyk GitHub Read-only Projects](scm-ide-and-ci-cd-workflow-and-integrations/git-repositories-scms-integrations-with-snyk/snyk-github-read-only-projects.md)
     * [Snyk GitLab integration](scm-ide-and-ci-cd-workflow-and-integrations/git-repositories-scms-integrations-with-snyk/snyk-gitlab-integration.md)
     * [Snyk Bitbucket Cloud integration](scm-ide-and-ci-cd-workflow-and-integrations/git-repositories-scms-integrations-with-snyk/snyk-bitbucket-cloud-integration.md)
-    * [Migrate a Bitbucket Cloud Personal Access Token](scm-ide-and-ci-cd-workflow-and-integrations/git-repositories-scms-integrations-with-snyk/migrate-a-bitbucket-cloud-personal-access-token.md)
+    * [Snyk Bitbucket Cloud (legacy) vs Snyk Bitbucket Cloud App](scm-ide-and-ci-cd-workflow-and-integrations/git-repositories-scms-integrations-with-snyk/snyk-bitbucket-cloud-legacy-vs-snyk-bitbucket-cloud-app.md)
     * [Snyk Bitbucket Cloud App integration](scm-ide-and-ci-cd-workflow-and-integrations/git-repositories-scms-integrations-with-snyk/snyk-bitbucket-cloud-app-integration.md)
     * [Snyk Bitbucket Data Center/Server integration](integrate-with-snyk/git-repositories-scms-integrations-with-snyk/snyk-bitbucket-data-center-server-integration.md)
     * [Snyk Azure Repositories (TFS) integration](scm-ide-and-ci-cd-workflow-and-integrations/git-repositories-scms-integrations-with-snyk/snyk-azure-repositories-tfs-integration.md)

docs/scm-ide-and-ci-cd-workflow-and-integrations/git-repositories-scms-integrations-with-snyk/snyk-bitbucket-cloud-app-integration.md

@@ -21,7 +21,7 @@ The Snyk Bitbucket Cloud App integration lets you connect your Snyk Organization
 {% hint style="info" %}
 Snyk recommends using the Bitbucket Cloud App integration for smoother integration and to ensure long-term support.
 
-If you are using the [Bitbucket Cloud Personal Access Token (Legacy) integration](snyk-bitbucket-cloud-integration.md), see [Migrate a Bitbucket Cloud Legacy integration](migrate-a-bitbucket-cloud-personal-access-token.md) for more information.
+If you are using the [Bitbucket Cloud Personal Access Token (Legacy) integration](snyk-bitbucket-cloud-integration.md), see [Migrate a Bitbucket Cloud Legacy integration](snyk-bitbucket-cloud-legacy-vs-snyk-bitbucket-cloud-app.md) for more information.
 {% endhint %}
 
 ## Setting up a Bitbucket Cloud App

docs/scm-ide-and-ci-cd-workflow-and-integrations/git-repositories-scms-integrations-with-snyk/snyk-bitbucket-cloud-integration.md

@@ -4,7 +4,7 @@
 **Feature availability**\
 This feature is available for all plans. See [pricing plans](https://snyk.io/plans/) for more details.
 
-Snyk recommends installing or [migrating](migrate-a-bitbucket-cloud-personal-access-token.md) to the [Bitbucket Cloud Application](snyk-bitbucket-cloud-app-integration.md) for smoother integration and to ensure long-term support.
+Snyk recommends installing or [migrating](snyk-bitbucket-cloud-legacy-vs-snyk-bitbucket-cloud-app.md) to the [Bitbucket Cloud Application](snyk-bitbucket-cloud-app-integration.md) for smoother integration and to ensure long-term support.
 {% endhint %}
 
 The Snyk Bitbucket Cloud (PAT) integration lets you:
@@ -137,11 +137,74 @@ When you disconnect Snyk from your repository Projects, your credentials are rem
 If you choose to re-enable this integration, you must re-enter your credentials and activate your Projects.
 {% endhint %}
 
-To disconnect this integration, in <img src="../../.gitbook/assets/cog_icon.png" alt="Settings" data-size="line"> (Organization settings)> **Integrations:**
+To disconnect this integration, in **Organization settings** > **Integrations:**
 
 1. In your list of integrations, select the Bitbucket integration you want to deactivate and click **Edit settings** to open a page with the current status of your integration.\
    \
    The page includes sections that are specific to each integration, where you can manage your credentials, API key, Service Principal, or connection details.
 2. Scroll to the relevant section and click **Disconnect.**
 
 <figure><img src="../../.gitbook/assets/mceclip2-4-.png" alt="Disconnect button at the bottom left of the Disconnect from Bitbucket Cloud section"><figcaption><p>Disconnect button at the bottom left of the Disconnect from Bitbucket Cloud section</p></figcaption></figure>
+
+## Migrate to the Snyk Bitbucket Cloud App
+
+This section describes how to migrate your existing [Bitbucket Cloud Personal Access Token (PAT) integration](snyk-bitbucket-cloud-integration.md), displayed in Snyk as Bitbucket Cloud (legacy), to the [**Bitbucket Cloud App**](snyk-bitbucket-cloud-app-integration.md) integration.
+
+To migrate to the new app integration, you must remove all the previously imported Projects from Snyk, delete the legacy PAT integration and its Projects, set up the new app integration, and reimport your Projects to Snyk from the new integration.
+
+{% hint style="info" %}
+Before going through the migration process, you should note that the following Project-level information will not persist:
+
+* Historic Project-related data, including trend numbers for fixing vulnerabilities
+* Project-related metadata: ignores and tags
+{% endhint %}
+
+### Migration process
+
+The migration process includes the following steps:
+
+1. [Deleting the existing Projects](snyk-bitbucket-cloud-integration.md#1.-delete-existing-projects) that are connected to the Bitbucket Cloud PAT (Legacy) integration in Snyk.
+2. [Disconnecting the Legacy integration in Snyk](snyk-bitbucket-cloud-integration.md#2.-disconnect-the-legacy-integration).
+3. [Removing the first-party extension](snyk-bitbucket-cloud-integration.md#3.-remove-the-snyk-tab-for-the-legacy-integration-in-bitbucket-cloud-optional) for the Legacy integration in Bitbucket (optional)
+4. [Connecting the Bitbucket Cloud App ](snyk-bitbucket-cloud-integration.md#set-up-the-new-bitbucket-cloud-app-integration.)and importing Projects.
+
+#### Delete existing Projects
+
+Delete all the existing Projects in Snyk that were previously imported from the Legacy integration. To use the bulk delete action on the Projects page, change the grouping filter to **Group by none**. You can now select multiple Projects in the list individually or by selecting the checkbox at the top to **Select all visible projects**. To delete a Project, select the trash icon, **Delete selected projects**.
+
+<figure><img src="../../.gitbook/assets/2023-11-20_14-29-35.png" alt="Change the Projects filter to Group by none"><figcaption><p>Change the Projects filter to <strong>Group by none</strong></p></figcaption></figure>
+
+<figure><img src="../../.gitbook/assets/2023-11-20_14-41-16.png" alt="Bulk delete the selected Projects" width="375"><figcaption><p>Bulk delete the selected Projects</p></figcaption></figure>
+
+#### Disconnect the Legacy integration
+
+To disconnect the Bitbucket Cloud (Legacy) integration, go to the settings page of Bitbucket Cloud (Legacy) integration, scroll to the relevant section, and click **Disconnect.**
+
+<figure><img src="../../.gitbook/assets/image (524).png" alt="Disconnect the Bitbucket Cloud PAT (Legacy) integration"><figcaption><p>Disconnect the Bitbucket Cloud PAT (Legacy) integration</p></figcaption></figure>
+
+#### Remove the Snyk tab for the Legacy integration in Bitbucket Cloud (optional)
+
+The Bitbucket Cloud (Legacy) has an optional first-party interface app for Bitbucket Cloud.
+
+This app can be installed on your Bitbucket Cloud workspace to enrich the legacy integration with a first-party interface as the "_**Snyk**_" tab)
+
+If you have used this app, before setting up the Snyk Bitbucket Cloud App in the next step, remove the Legacy interface app in Bitbucket Cloud.\
+This functionality is supported out-of-the-box in the Snyk App integration.\
+\
+Go to your **Workspace settings** page in **Bitbucket.org > Manage installed apps**, expand the **Snyk Security for Bitbucket Cloud** app, and click **Remove.**
+
+<figure><img src="../../.gitbook/assets/remove_snyk-security-bbc_11oct2022.png" alt="Remove the first-party Snyk Legacy interface app in Bitbucket"><figcaption><p>Remove the first-party Snyk Legacy interface app in Bitbucket</p></figcaption></figure>
+
+#### Set up the Bitbucket Cloud App integration
+
+See the [Bitbucket Cloud App integration](snyk-bitbucket-cloud-app-integration.md) topic for instructions.
+
+### Migration demo
+
+In less than five minutes, Marco Morales, a Partner Solutions Architect at Snyk, talks about the Snyk Bitbucket Cloud App and goes through the process of migrating an existing Legacy integration to the Snyk Bitbucket Cloud App.
+
+_Go to timestamp 2:34 to jump right into the demo._
+
+{% embed url="https://thoughtindustries-1.wistia.com/medias/32rgw3hkdk" %}
+How to migrate to the new Snyk Bitbucket Cloud App integration
+{% endembed %}

docs/scm-ide-and-ci-cd-workflow-and-integrations/git-repositories-scms-integrations-with-snyk/snyk-bitbucket-cloud-legacy-vs-snyk-bitbucket-cloud-app.md

@@ -0,0 +1,23 @@
+# Snyk Bitbucket Cloud (legacy) vs Snyk Bitbucket Cloud App
+
+In general, Snyk recommends using the new Bitbucket app integration. However, the new integration does not fit all cases. The information in this section is intended to help you decide which integration is right for you.
+
+See [Migrate to the Snyk Bitbucket Cloud App](snyk-bitbucket-cloud-integration.md#migrate-to-the-snyk-bitbucket-cloud-app) for detailed migration instructions.
+
+### Main capabilities unlocked by the new app integration
+
+* Allows using Snyk with Bitbucket's [allowlisting IP addresses](https://support.atlassian.com/bitbucket-cloud/docs/control-access-to-your-private-content/) premium tier feature.
+* Helps handle rate-limiting issues for companies who spread their repos across multiple workspaces in Bitbucket Cloud.
+* Supports the first-party interface in Bitbucket Cloud (Snyk's Security tab) out-of-the-box, meaning you need not install and maintain the first-party extension app to consume Snyk's security insights from Bitbucket Cloud.
+
+### Limitations of the new app integration
+
+* In the new app integration, every Snyk Organization can connect to only one workspace in Bitbucket Cloud. If you want to import Projects from various workspaces in Bitbucket into the same single Organization in Snyk, use the PAT integration.
+* The new app integration does not yet support Snyk Multi-Tenant EU, Snyk Multi-Tenant AUS, and Snyk Single-Tenant cloud deployments.
+* For customers who are part of the custom branch closed beta, the new app integration's first-party interface in Bitbucket Cloud does not allow importing Projects from non-default branches. It is possible to import a non-default branch; you must do it from the Snyk.io import modal.
+
+### Are there any plans for end-of-life for the Personal Access Token (PAT) integration?
+
+No, the Personal Access Token Bitbucket Cloud integration is fully supported, and there are no plans to stop supporting it.
+
+However, there is a first-party interface _extension_ app that serves as an extension layer to the PAT integration, allowing developers to consume Snyk's findings from within the Bitbucket interface. This extension app was developed and supported by an external contractor company. As this functionality is now an integral part of the new app integration, the extension app has now moved to no-support mode, meaning that customers who use the PAT integration alongside the first-party extension app must migrate to the new app integration to get support for the first-party interface functionality.