Integrations: update Bitbucket guides

docs/cloud/bitbucket-server-integration-setup.md

@@ -1,36 +1,67 @@
 # Bitbucket Data Center / Server Integration Setup
 ## Private Packagist Cloud
 
+<div class="row column">
+    <div class="callout success">
+        <p>
+            This guide explains how to set up an OAuth integration for Private Packagist Cloud with Bitbucket Data Center / Server.
+            If you use their public service on bitbucket.org, these instructions are not relevant to you. 
+        </p>
+        <p>If you are using our Self-Hosted product, please <a href="/docs/self-hosted/bitbucket-server-integration-setup.md">use this guide</a>.</p>
+    </div>
+</div>
+
 <div class="row column">
     <div class="callout warning">
         <p>Note: Application Links using OAuth 2 are available since Bitbucket Data Center / Server v7.21. If you are using an older Bitbucket Data Center / Server version then consult the <a href="/docs/cloud/bitbucket-server-oauth1-integration-setup.md">Bitbucket Data Center / Server OAuth 1 setup guide</a>.</p>
     </div>
 </div>
 
-## Initial Setup
-From the organization settings page, select the "Integrations" subtab.
-Hit the "Add Integration" button on the integrations listing page to get to the form below.
-To set up a Bitbucket Data Center / Server integration with Private Packagist, start by selecting "Bitbucket Data Center / Server"
-as the platform, enter the URL of your on-premise Bitbucket Data Center / Server into the base URL field and select OAuth 2 as the OAuth version as seen in the example below.
+To allow your users to authenticate to Private Packagist with their Bitbucket Data Center / Server account, you'll
+first need to create an integration in Private Packagist. This document walks you through the required steps.
 
-![Packagist Setup](/Resources/public/img/docs/integration-setup/cloud/bitbucket-server-01-packagist-setup.png)
+## Open the Add Integration form
+From the organization settings page, select the "Integrations" subtab. Hit the "Add Integration" button on the integrations listing page to get to the form below.
+To set up a Bitbucket Data Center / Server integration with Private Packagist start by selecting "Bitbucket Data Center / Server" as the platform, enter 
+the URL of your on-premise Bitbucket server into the base URL field and select OAuth 2 as the OAuth version as seen in the example below.
 
-Copy the content from the "Callback URL / Redirect URL" field and follow the link to set up an Application Link.
+A link to create a new OAuth application on your Bitbucket Data Center / Server instance will automatically be displayed.
+
+![Packagist Setup](/Resources/public/img/docs/integration-setup/cloud/bitbucket-server-01-packagist-setup-20250102.png)
 
 ## Configure Application link
-Click on the link to setup an Application Link on Bitbucket Data Center / Server and select "External application" as type and "Incoming" as direction.
+Do not submit the integration form yet, but copy the content from the "Callback
+URL / Redirect URL" and follow the setup link to your Bitbucket Data Center / Server instance. The fields
+Client ID and Client Secret remain empty for now.
+
+In Bitbucket Data Center / Server, click on the "Create link" button and select "External application" as type and "Incoming" as direction.
 
-![Bitbucket Data Center / Server Create Application Link](/Resources/public/img/docs/integration-setup/bitbucket-server-02-bitbucket-create-application-link.png)
+![Bitbucket Data Center / Server Create Application Link](/Resources/public/img/docs/integration-setup/bitbucket-server-02-bitbucket-create-application-link-20250102.png)
 
 After you click the button to continue, enter a name and the content from the "Callback URL / Redirect URL" from the Private Packagist form.
 Select Repositories "Read" as application permission and save the form.
 
-![Bitbucket Data Center / Server Configure Application Link](/Resources/public/img/docs/integration-setup/bitbucket-server-03-bitbucket-configure-application-link.png)
+![Bitbucket Data Center / Server Configure Application Link](/Resources/public/img/docs/integration-setup/cloud/bitbucket-server-03-bitbucket-configure-application-link.png)
+
+Once the form is saved, Bitbucket Data Center / Server will show you the Client ID and secret.
 
 ## Finish the Setup
+Copy and paste the "Client ID" and "Client Secret" values back into the Private
+Packagist integration form and submit the form with the "Create Integration"
+button.
 
-Once the form is saved, Bitbucket Data Center / Server will show you the Client ID and secret.
-Copy them over to Private Packagist and save the integration.
+![Packagist Finalize](/Resources/public/img/docs/integration-setup/cloud/bitbucket-server-04-packagist-finalize.png)
+
+You'll be redirected back to the list of integrations.
+
+### Share the Bitbucket login link
+
+The final step is sharing your organization-specific login link with your users. Look for the "Login link" button next to
+your newly created Bitbucket Data Center / Server integration on the integrations page, and copy the URL.
+
+![Bitbucket Data Center / Server integrations](/Resources/public/img/docs/integration-setup/cloud/bitbucket-server-05-integrations-overview.png)
+
+This link presents the option to authenticate with your Bitbucket Data Center / Server account and can now be used to log in to Private Packagist.
 
 ## Configure Bitbucket Server plugins
 

docs/cloud/bitbucket-server-oauth1-integration-setup.md

@@ -1,6 +1,16 @@
 # Bitbucket Data Center / Server Integration Setup (OAuth 1)
 ## Private Packagist Cloud
 
+<div class="row column">
+    <div class="callout success">
+        <p>
+            This guide explains how to set up an OAuth 1 integration for Private Packagist Cloud with Bitbucket Data Center / Server.
+            If you use their public service on bitbucket.org, these instructions are not relevant to you. 
+        </p>
+        <p>If you are using our Self-Hosted product, please <a href="/docs/self-hosted/bitbucket-server-oauth1-integration-setup.md">use this guide</a>.</p>
+    </div>
+</div>
+
 <div class="row column">
     <div class="callout warning">
         <p>
@@ -12,18 +22,20 @@
     </div>
 </div>
 
-## Initial Setup
+To allow your users to authenticate to Private Packagist with their Bitbucket Data Center / Server account, you'll
+first need to create an integration in Private Packagist. This document walks you through the required steps.
 
+## Open the Add Integration form
 From the organization settings page, select the "Integrations" subtab.
 Hit the "Add Integration" button on the integrations listing page to get to the form below.
 To set up a Bitbucket Data Center / Server integration with Private Packagist, start by selecting "Bitbucket Data Center / Server"
 as the platform, enter the URL of your on-premise Bitbucket Data Center / Server into the base URL field and select OAuth 1 as the OAuth version as seen in the example below.
 
-![Packagist Setup](/Resources/public/img/docs/integration-setup/cloud/bitbucket-server-oauth1-01-packagist-setup.png)
+![Packagist Setup](/Resources/public/img/docs/integration-setup/cloud/bitbucket-server-oauth1-01-packagist-setup-20250103.png)
 
 Submit the form to see the additional information.
 
-![Packagist Form](/Resources/public/img/docs/integration-setup/cloud/bitbucket-server-oauth1-02-packagist-details.png)
+![Packagist Form](/Resources/public/img/docs/integration-setup/cloud/bitbucket-server-oauth1-02-packagist-details-20250103.png)
 
 ## Configure Application link
 Click on the link to setup an Application Link on Bitbucket Data Center / Server. You will need the "Client Id" and the "Public Key" shown in the form.
@@ -32,7 +44,7 @@ Click on the link to setup an Application Link on Bitbucket Data Center / Server
 
 For Bitbucket Data Center versions 7.21 and newer, select "Atlassian product" and not "External application" to be able to set up an OAuth1 link.
 
-After you hit the button to create a new Application Link a configuration window may appear. If it does, verify that the url matches your Private Packagist URL and hit "Continue", otherwise skip this step.
+After you hit the button to create a new Application Link a configuration window may appear. If it does, verify that the url matches the "Application URL for Link" (_https://packagist.com_) and hit "Continue", otherwise skip this step.
 
 ![Bitbucket Data Center / Server Invalid Url](/Resources/public/img/docs/integration-setup/bitbucket-server-oauth1-04-bitbucket-invalid-url.png)
 
@@ -48,7 +60,15 @@ Click on the pen icon to the right of the application you just created to edit t
 
 This is where we will need the "Client ID" and the "Public Key" that were previously generated on the Private Packagist integration form.
 Enter the "Client ID" into the "Consumer Key" field, make sure the entire content of the "Public Key" field gets copied and the "Consumer Callback" field stays empty.
-Submit the form and go back to Private Packagist.
+Submit the form and go back to the list of integrations in Private Packagist.
+
+### Share the Bitbucket login link
+The final step is sharing your organization-specific login link with your users. Look for the "Login link" button next to
+your newly created Bitbucket Data Center / Server integration on the integrations page, and copy the URL.
+
+![Bitbucket Data Center / Server integrations](/Resources/public/img/docs/integration-setup/cloud/bitbucket-server-oauth1-08-integrations-overview.png)
+
+This link presents the option to authenticate with your Bitbucket Data Center / Server account and can now be used to log in to Private Packagist.
 
 ## Configure Bitbucket Server plugins
 

docs/self-hosted/bitbucket-integration-setup.md

@@ -2,32 +2,50 @@
 ## Private Packagist Self-Hosted
 
 <div class="row column">
-    <div class="callout warning">
-        <p>Note: The instructions on this page create an integration with the public Bitbucket at bitbucket.org. If you are trying to setup an integration with your own Bitbucket Data Center / Server consult the <a href="/docs/self-hosted/bitbucket-server-integration-setup.md">Bitbucket Data Center / Server setup guide</a>.</p>
+    <div class="callout success">
+        <p>
+            This guide explains how to set up an OAuth integration for Private Packagist Self-Hosted with the public service on Bitbucket.org.
+            If you use Bitbucket Data Center / Server instead, consult <a href="/docs/self-hosted/bitbucket-server-integration-setup.md">this guide for Self-Hosted</a>.
+        </p>
+        <p>If you are using our Cloud product at packagist.com, this page is not relevant to you.</p>
     </div>
 </div>
 
-## Initial Setup
-Hit the “Add Integration“ button on the admin page to get to the form below.
+To allow your users to authenticate to Private Packagist Self-Hosted with their Bitbucket account, you'll
+first need to create an integration in Private Packagist. This document walks you through the required steps.
+
+## Open the Add Integration form
+Go to the Admin section and hit the “Add Integration“ button to open the form to create your integration. If you've just
+installed Private Packagist Self-Hosted and it is still running in Setup Mode, you do not need to log in. If the application
+is no longer in Setup mode, you will have to log in with an admin account first.
 
 ![Add Integration](/Resources/public/img/docs/self-hosted/08-integration-create.png)
 
 To setup a Bitbucket integration with Private Packagist start by selecting "Bitbucket" as the platform and enter <i>https://bitbucket.org</i> as the base URL, as seen in the example below.
+A link to set up the OAuth application on Bitbucket will automatically be displayed.
 
-![Packagist Setup](/Resources/public/img/docs/integration-setup/bitbucket-01-packagist-setup.png)
+![Packagist Setup](/Resources/public/img/docs/integration-setup/self-hosted/bitbucket-01-packagist-setup.png)
 
 ## Creating an OAuth Application
-Do not submit the integration form yet, but copy the content from the "Callback URL / Redirect URL" and go to <a href="https://bitbucket.org/account">https://bitbucket.org/account</a>. Find the "OAuth" menu item under "Access Management" and click on "Add consumer".
-
-![Bitbucket Form](/Resources/public/img/docs/integration-setup/bitbucket-02-bitbucket-form.png)
+Do not submit the integration form yet, the fields  Client ID and Client Secret remain empty for now. 
+Copy the content from the "Callback URL / Redirect URL" and open the setup link to your Bitbucket 
+account. Replace the `<WORKSPACE_NAME>` string in the setup link with your actual Bitbucket workspace name.
 
-Make sure all the scopes listed on the Private Packagist form are checked and save the new consumer.
+![Bitbucket Form](/Resources/public/img/docs/integration-setup/self-hosted/bitbucket-02-bitbucket-form.png)
 
-![Bitbucket Form](/Resources/public/img/docs/integration-setup/bitbucket-03-bitbucket-reveal-key.png)
+Make sure all the scopes listed on the Private Packagist form are checked and save the new consumer. Click on the consumer 
+you just created to reveal the credentials required to finish the setup on Private Packagist.
 
-Click on the consumer you just created to reveal the credentials required to finish the setup on Private Packagist.
+![Bitbucket Form](/Resources/public/img/docs/integration-setup/self-hosted/bitbucket-03-bitbucket-reveal-key.png)
 
 ## Finish the Setup
 Copy and paste the "Key" and "Secret" values back into the Private Packagist integration form and submit the form with the "Create Integration" button.
 
-![Bitbucket Form](/Resources/public/img/docs/integration-setup/bitbucket-04-packagist-form.png)
+![Bitbucket Form](/Resources/public/img/docs/integration-setup/self-hosted/bitbucket-04-packagist-form.png)
+
+The Bitbucket integration will be created and you will be redirected to the admin page.
+
+The new integration will be shown in the list of available integrations, and your users can
+now log in to your Private Packagist Self-Hosted installation using their Bitbucket account.
+
+![Available integrations](/Resources/public/img/docs/integration-setup/self-hosted/bitbucket-05-integrations-overview.png)

docs/self-hosted/bitbucket-server-integration-setup.md

@@ -1,26 +1,44 @@
 # Bitbucket Data Center / Server Integration Setup
 ## Private Packagist Self-Hosted
 
-This guide explains how to setup an OAuth integration for Private Packagist Self-Hosted with Bitbucket Data Center / Server integration.  
-If you are using our cloud product at packagist.com, [use this guide](../cloud/bitbucket-server-integration-setup.md).
+<div class="row column">
+    <div class="callout success">
+        <p>
+            This guide explains how to set up an OAuth integration for Private Packagist Self-Hosted with Bitbucket Data Center / Server.
+            If you use their public service on bitbucket.org, follow <a href="/docs/self-hosted/bitbucket-integration-setup.md">these instructions</a>.
+        </p>
+        <p>If you are using our Cloud product at packagist.com, <a href="/docs/cloud/bitbucket-server-integration-setup.md">use this guide</a>.</p>
+    </div>
+</div>
 
 <div class="row column">
     <div class="callout warning">
         <p>Note: Application Links using OAuth 2 are available since Bitbucket Data Center / Server v7.21. If you are using an older Bitbucket Data Center / Server version then consult the <a href="/docs/self-hosted/bitbucket-server-oauth1-integration-setup.md">Bitbucket Data Center / Server OAuth 1 setup guide</a>.</p>
     </div>
 </div>
 
-## Initial Setup
-Hit the “Add integration“ button on the admin page to get to the form below.
+To allow your users to authenticate to Private Packagist Self-Hosted with their Bitbucket Data Center / Server account, you'll
+first need to create an integration in Private Packagist. This document walks you through the required steps.
+
+## Open the Add Integration form
+Go to the Admin section and hit the “Add Integration“ button to open the form to create your integration. If you've just
+installed Private Packagist Self-Hosted and it is still running in Setup Mode, you do not need to log in. If the application
+is no longer in Setup mode, you will have to log in with an admin account first.
+
+![Add Integration](/Resources/public/img/docs/self-hosted/08-integration-create.png)
+
 To setup a Bitbucket Data Center / Server integration with Private Packagist, start by selecting "Bitbucket Data Center / Server"
-as the platform, enter the URL of your on-premise Bitbucket Data Center / Server into the base URL field and select OAuth 2 as the OAuth version as seen in the example below.
+as the platform, enter the URL of your on-premise Bitbucket Data Center / Server into the base URL field and select OAuth 2 
+as the OAuth version as seen in the example below. A link to set up the OAuth application on your Bitbucket instance will automatically be displayed.
 
-![Packagist Setup](/Resources/public/img/docs/integration-setup/bitbucket-server-01-packagist-setup.png)
+![Packagist Setup](/Resources/public/img/docs/integration-setup/self-hosted/bitbucket-server-01-packagist-setup.png)
 
-Copy the content from the "Callback URL / Redirect URL" field and follow the link to set up an Application Link.
+## Create Application link
+Do not submit the integration form yet, but copy the content from the "Callback
+URL / Redirect URL" and follow the setup link to your Bitbucket Data Center / Server instance. The fields
+Client ID and Client Secret remain empty for now.
 
-## Configure Application link
-Click on the link to setup an Application Link on Bitbucket Data Center / Server and select "External application" as type and "Incoming" as direction.
+In Bitbucket, click on the "Create link" button and select "External application" as type and "Incoming" as direction.
 
 ![Bitbucket Data Center / Server Create Application Link](/Resources/public/img/docs/integration-setup/bitbucket-server-02-bitbucket-create-application-link.png)
 
@@ -29,12 +47,21 @@ Select Repositories "Read" as application permission and save the form.
 
 ![Bitbucket Data Center / Server Configure Application Link](/Resources/public/img/docs/integration-setup/bitbucket-server-03-bitbucket-configure-application-link.png)
 
+Once the form is saved, Bitbucket Data Center / Server will show you the Client ID and secret.
+
 ## Finish the Setup
+Copy and paste the "Client ID" and "Client Secret" values back into the Private
+Packagist integration form and submit the form with the "Create Integration"
+button.
 
-Once the form is saved, Bitbucket Data Center / Server will show you the Client ID and secret.
-Copy them over to Private Packagist and save the integration. 
+![Packagist Finalize](/Resources/public/img/docs/integration-setup/self-hosted/bitbucket-server-04-packagist-finalize.png)
+
+The Bitbucket integration will be created and you will be redirected to the admin page.
+
+The new integration will be shown in the list of available integrations, and your users can
+now log in to your Private Packagist Self-Hosted installation using their Bitbucket Data Center / Server account.
 
-![Packagist Finalize](/Resources/public/img/docs/integration-setup/bitbucket-server-04-packagist-finalize.png)
+![Available integrations](/Resources/public/img/docs/integration-setup/self-hosted/bitbucket-server-05-integrations-overview.png)
 
 ## Configure Bitbucket Server plugins