Email about ending Bitbucket Services feature

[#1]

Hello! Many of you received an email about Bitbucket ending support for the Services feature on 31 December 2021. We apologize that this has caused some confusion among our admins. 

Most of the confusion has come from admins not being able to identify the repository that is still utilizing the Services feature and migrating to Bitbucket webhooks. If you are using the Services feature, here is how you migrate to webhooks. 

We are currently working on a fix to help with this and will update this post with how to go about working through this soon! But you can obtain a list of affected repositories by reaching out to our support team. 

We appreciate your patience as we work on getting this fix out!

Thank you!

[David Dansby]

Update 2:

There have been a number of admins who have reported to us that they have existing POST and Pull Request POST Services with a URL like so

https://[accountname].atlassian.net/rest/bitbucket/1.0/repository/[repo-id]/sync

This is an old, carry-over from how Bitbucket Cloud used to integrate with the Jira. None of the supported versions of Jira Cloud and Jira Server/DC no longer integrate with Bitbucket Cloud using Services.

Most of these integrations to Bitbucket Cloud have been updated to

• Jira Cloud: now utilizes the simple point-and-click method for integrating Jira Cloud with Bitbucket Cloud
• Jira Server/Data Center (version 8.7.x and above): now utilizes webhooks to integrate with Bitbucket Cloud
  • Admin can either:
    • https://support.atlassian.com/bitbucket-cloud/docs/connect-bitbucket-cloud-to-jira-software-server/
    • https://confluence.atlassian.com/jirakb/upgrade-the-jira-dvcs-connector-plugin-in-jira-server-967900869.html

So, what must admins do with these specific types of POST and Pull Request POST Services that were originally used to integrate Jira to Bitbucket Cloud?

• Jira Cloud: ensure you are integrated with Bitbucket Cloud using the one of the following methods:
  • Note: a Jira admin is required to approve the Bitbucket Cloud integration
  • From Bitbucket Cloud: 
    • https://support.atlassian.com/bitbucket-cloud/docs/connect-bitbucket-cloud-to-jira-software-cloud/
  • From Jira Cloud: 
    • https://support.atlassian.com/jira-cloud-administration/docs/connect-jira-cloud-to-bitbucket/
  • After the integration is confirmed to be set up properly the two old, existing Services originally used to integrate with Jira from the original integration method can be ignored (there is no required to remove them; they will be removed as part of the Services feature removal and should not impact the updated integration method)
• Jira Server/Data Center (DC): ensure you are on a supported Jira version  (8.7 and above; Jira 8.6 support will end very soon on 17 December 2021)
  • Follow this guide to ensure the integration is set up properly: 
    • https://support.atlassian.com/bitbucket-cloud/docs/connect-bitbucket-cloud-to-jira-software-server/
  • After the integration is confirmed to be set up properly the two old, existing Services originally used to integrate with Jira from the original integration method can be ignored (there is no required to remove them; they will be removed as part of the Services feature removal and should not impact the updated integration method)
  • Note: sometimes users may need to update the DVCS plugin (although updated versions of Jira should come with the updated versions of the DVCS plugin)
    • https://confluence.atlassian.com/jirakb/upgrade-the-jira-dvcs-connector-plugin-in-jira-server-967900869.html
• For any Bitbucket Cloud integrations with versions of Jira Server/DC less than 8.7
  • These Jira Server/DC versions are no longer supported and users will need to go through the upgrade process referenced above for Jira Server/DC, but it will be outside the scope of Atlassian support (given Jira Server/DC versions before 8.7 are no longer supported by Atlassian)
  • **Note**: currently version 8.6 is supported, but support will end very soon on 17 December 2021. After this date upgrading 8.6 and below will be out of the scope of Atlassian support

Update:

The API endpoint URL has been updated to expand the response pagelen and include the next field. Instructions have been updated accordingly. This will help those admins who were only getting HTTP responses with empty arrays for the responses services values, which was most likely due to the workspace having 10s or 100s of repositories which requires paginated HTTP responses.

Original message:

Hello! I wanted to provide a further update to the fix referenced above, but first, let me start by saying we are sorry for the confusion the original email has caused and wish to thank you for your continued patience and support of Bitbucket and our amazing community/support team.

First, for clarification we are not requiring repository admins to disconnect or remove existing Services; we are only suggesting migrating any Service functionality you wish to keep to webhooks. Here is some documentation about webhooks and a tutorial for creating a webhook.

Currently, repository admins can determine what Services are enabled on a repository by doing the following:

1. Navigate to the repository
2. From there, find and select Repository settings on the left-hand navigation bar
3. In Repository settings, on the left-hand navigation bar, under Workflow, you should see a Services page. Click it. If you do not see a Services page then that means you do not have any services enabled on the repository.
4. Once the page has loaded you should see the Services the repo has

However, we are aware that for those admins that have 10s or 100s of repositories this is very untenable. So, we have provided expanded functionality to our API so that you can quickly pull all services for your repositories in each Bitbucket workspace (for which you are an admin). The process to do this is as follows:

1. Ensure you are authenticated for making API calls to the Bitbucket API. More info on authentication can be found here 
2. Once authentication is setup send an HTTP GET request to the following API endpoint with your favorite API client (please ensure you replace {workspace-slug} with the workspace slug you wish to search; the workspace slug is the URL-friendly version of the workspace name you see in the URL when located in your workspace):

https://api.bitbucket.org/2.0/repositories/{workspace-slug}/?pagelen=100&fields=values.services.*.*.*,values.full_name,next&role=admin

• Note, the endpoint above will return a list of repositories in the workspace (for which you are an admin) along with Service names. The endpoint will also provide a URL to the Service’s corresponding repository settings Services page. There you will find more information about your Service. For example, if you need the URL associated with a Post Service this will be contained in that Services page. This is info that will be needed if you wish to migrate the functionality to a webhook.
• If you have admin access to more than 100 repositories within the workspace you are searching you will be required to paginate through the API responses by successively sending an HTTP GET request to the endpoint provided in the response's next field's value in order to search all repositories with Services in the workspace.
• Furthermore, you may see an empty array value for the services field in the HTTP response which indicates the repository in that workspace does not have any Services.

Lastly, some of the services your repository may have installed are integrations that no longer exist or have so significantly changed that the service was no longer working already. Some specific examples that we are aware of are:

• Masterbranch
• Rietveld
• FriendFeed
• HipChat

Thank you,

The Bitbucket team

[vipulpambhar]

@David thanks for your reply!

We dont have any services on a repository so you mean that, we do not need to do anything for it right?

Thanks for all your help and support!

[David Dansby]

@vipulpambhar that is correct. We are only asking admins that don't want to lose any specific Service functionality already enabled for a particular repository to migrate over to webhooks. We are not asking admins to disable/remove any Services they no longer wish to use and/or migrate over to webhooks.

Best,

David

[Chris Speier]

I see 2 services calling our on-prem jira.   https://jira.xxx.com/rest/bitbucket/1.0/repository/1/sync

jira pull - with the same address.  any thoughts/suggestions on how to convert to webhook?

[David Dansby]

@Chris Speier I am a bit confused. What are the Service types/names for these two? We do not have a "jira" and a "jira pull" Service type/name. Once I know the actual Service type I can provide better information. 

[jamesholcomb]

- Why are Services going away?

- Are all existing Services non-functioning on Jan 1 2022?

- What functions do repositories lose when Services are discontinued?

- How do I tell what my existing services do (I only see a list of POST urls)?

- The 'tutorial' link you referenced is not sufficient for migration.  Please provide a document that provides a step by step guide to _migrating_ a service to a wehbook.

Thanks!

[Paul Nguyen]

Hi,

I've queried the endpoint and it returns me the list of some repos with all empty array `services`. But why I still receive this email from Bitbucket?

Thanks,

Paul

[Mads K]

David Dansby: We have the same services present in most of our repos. Looks like it syncs Jira with Bitbucket, but it must be something the integration created automatically for all those repos. Can the Jira-Bitbucket-integration auto-handle these things now? Why can't Atlassian auto-convert them to webhooks if that isn't the case? We have 108 affected repos. The text above the URL is the service-type.
 

POST
 https://xxx.jira.com/rest/bitbucket/1.0/repository/77/sync
Pull Request POST
 https://xxx.jira.com/rest/bitbucket/1.0/repository/77/sync

Also, just like the comment above, we just get an empty array when using the new services-endpoint, even though we actually have services.

[Pim]

Just like above (getting the email, but no listed services in the API).

The response being:

{"values": []}

[Nicolas Rozier]

Same for me (got email, but no listed services)

It turned out that I was admin for only a subset of all workspace repos. I could identify the repos that did have services, by removing the role=admin part from query

https://api.bitbucket.org/2.0/repositories/{workspace-slug}/?fields=values.services.*.*.*,values.full_name

[Dean]

Hi,

With help, I located one of several repos using the API call where Services are being rendered per your comments above.  However, when I look at a specific repo, there is not an option under Workflow labeled as Services.

I do have a listing for Webhooks and when clicking on it, I can see the webhook in question that is returned in the Services API call.

I'm curious, if it is already a Webhook, is there anything else we need to do then?

[Kjartan Clausen]

@David Dansby Do you have some better documentation for how to find out which of the hundreds of repos I manage has services enabled?
That "tutorial" above is a joke. 

When something big like this happens you should have an easy to understand, step-by-step manual for us to follow.

And honestly, you should provide us with a list of the repos in our workspaces that are using the deprecating services. We shouldn't have to spend hours installing software and debugging apps that other customers have created in order to try to find the repos, trying fix an issue you are creating! We'll have more than enough to do trying to fix the services that will break!

[David Dansby]

Sorry for the delayed response.

To those only seeing responses with an empty array for Services value please read the following:

Since we are filtering fields in the HTTP response via the URL query parameters, for those workspaces with 10s or 100s of repositories the fact that the URL query parameters do not include the next field causes that field to be excluded in the response value which is responsible for the next paginated response (i.e. we could be leaving off response values from the original API query). Furthermore, the lack of utilizing the pagelen query parameter to increase the number of objects in each HTTP response further adds to this issue.

So, I have updated the instructions in my original comment (please re-read my original post at the top of this page) that showcases updated instructions to go along with the following updated API endpoint URL:

https://api.bitbucket.org/2.0/repositories/{workspace-slug}/?pagelen=100&fields=values.services.*.*.*,values.full_name,next&role=admin

[David Dansby]

@Dean does the repo in question have any other admins? It could be the case that someone else you work with has already migrated the Services to a webhook and removed the Service in the Services settings page. Once all services are removed from a repository the Services settings page is no longer displayed.

This was carried over from the original work to remove the Services feature back in July 2019 (https://support.atlassian.com/bitbucket-cloud/docs/view-end-of-support-announcements-for-bitbucket-cloud/?utm_source=alert-email&utm_medium=email&utm_campaign=bb-service-feature_EML-11583&jobid=105241631&subid=1521270630). 

[David Dansby]

@Mads K those JIRA URLs are for a on-prem JIRA, similar to @Chris Speier 's, correct???

[Pim]

@David Dansby using the updated API URL with pagelen and next field on a workspace with over 400 repositories I'm still just getting an empty values array as the response.

I would expect a next field value for successive API calls.

I'm using Postman with basic auth.

[Mads K]

@David Dansby No, this is JIRA-cloud as well as Bitbucket-cloud. No on-prem. You are more than welcome to verify the cloud-instances my account is linked to :)

[cdm-atlassian]

Good morning,
I'm lost, I have a workspace with over 90 repositories. Will I have to change them 1 to 1?

[Chris Speier]

Yes, those links are to our on-prem jira..  

[cdm-atlassian]

Is there any place that has a step by step to do this?
I'm still completely lost.

[David Dansby]

@cdm-atlassian The first thing you need to do is determine which repositories have Services and what those Services are based on the instructions in my original post at the top of this community page. After you determine those Services it is up to you whether you want to migrate those Services to webhooks or not. If you don't want to migrate then you can ignore those Services. However, yes, unfortunately, if you want to migrate to webhooks, you will have to migrate each service for each repository. 

Here is an example for migrating the two most common Service types, POST and Pull Request POST Service. Those two are relatively easy to migrate. For example, for a specific POST Service:

1. Navigate to Webhooks repository settings page
2. Click the Add webhook button
3. Give you webhook a Title
4. Copy and paste the URL for the POST Service into the URL field for your new webhook
5. Adjust Status and SSL/TLS settings accordingly
6. For triggers, make sure it is set to Repository:Push (this should be the default)
7. What the service the webhook sends the event payload to does with said payload is up to the owner of that service.

For Pull Request POST Service, the steps would be the same, except the triggers would instead be  1 or more of the Pull Request triggers provided. So, for example, if you select Pull Request:Created then when a Pull Request is created the event payload data (specifically the Pull Request created event data) will be sent to the URL you provide. More information about event payload data and the different types can be found here. 

[David Dansby]

@Pim there should be a next field in the response if you used the updated URL I provided yesterday. You would then make successive HTTP GET method calls to the URL value provided in the value of the next field.

https://api.bitbucket.org/2.0/repositories/{workspace-slug}/?pagelen=100&fields=values.services.*.*.*,values.full_name,next&role=admin

[David Dansby]

hey  @jamesholcomb great questions! Let me try and answer each one accordingly:

1. Why are Services going away?
   1. We had originally made the push in Mid 2019 to remove the Services for webhooks but for some reason unknown to me it was never finalized. This was referenced in the very first email at the start of November 2021.
   2. This work is to finally remove Services, given webhooks replaces Services.
   3. Furthermore, as noted in my original comment there are a number of Services integrations that no longer work. So, the Service may be sending the event payload, but the integration with, say HipChat, obviously no longer works properly given HipChat no longer exists. Webhooks will work correctly so long as the event data that the webhooks send is handled correctly at the destination URL.
2. Are all existing Services non-functioning on Jan 1, 2022?
   1. We will be running a feature rollout, so not ALL Services will stop functioning on January 1, 2022. However, we cannot ensure your repositories will not be impacted on the start date, and thus, strongly recommend all admins ensure they migrate any functionality they wish to keep over to webhooks immediately.
   2. If you do not wish to keep the functionality for a specific Service then you don't need to do anything (for that Service).
   3. During the feature rollout, the Services will stop functioning but for those repositories with existing Services we will still list them on the Services page for a month or two to ease with migration. However, it should be noted that this page could be removed at any time starting January 1, 2022, and thus, we strongly urge admins to migrate any Service functionality they wish to keep to webhooks.
3. What functions do repositories lose when Services are discontinued?
   1. The only functionality that will be lost is directly related to the Services themselves. The repository will still function normally elsewhere. 
   2. For example, if the Bitbucket Cloud repository has a single POST Service then if you do nothing, the only thing that will occur once Services are removed is that for every code push to the Bitbucket Cloud repository in question Bitbucket will no longer send the associated event payload to the URL of the corresponding POST Service.
4. How do I tell what my existing services do (I only see a list of POST urls)?
   1. For POST services: whenever a user pushes code to the Bitbucket Cloud repository the POST Service sends an event payload as an HTTP POST method to the URL specified by the POST Service in question (this URL was provided by whoever set up the specific Service. How the event payload data is handled is up to the URL/service receiving the event payload; all this POST Service does is send the event payload on each code push to the cloud repository). More info about the event payloads can be found here. If you still want to send the same event payload to those URLs referenced in the POST Service then you would need to set up a webhook for that URL.
5. The 'tutorial' link you referenced is not sufficient for migration. Please provide a document that provides a step by step guide to migrating a service to a wehbook.
   1. In fact, the tutorial provided is essentially showing you how to set up a webhook for a POST Service, except you don't have to set up the actual service like the tutorial showcases, so long as you already have the URL for the service you want to continue sending the event payload to.
   2. I can provide the following steps in (3) below to migrate an existing POST Service, but first, can you please verify that the URLs associated with those POST Services are not similar to this
      1. https://xxx.jira.com/rest/bitbucket/1.0/repository/{repo-id}/sync
      2. If it is similar to this, can you please tell me the type of the Jira site instance before proceeding to step 3 below. Is it Jira Cloud or Jira Server/Data Center?
      3. If it is an unrelated URL then you can follow the steps in (3) below to migrate the existing POST Service to a webhook
   3. So, if you want to migrate an existing POST Service, then you would take the existing URL for that POST Service, and then you would do the following:
      1. Navigate to the repository settings page
      2. Next, navigate to the Webhooks settings page
      3. Click the Add webhook button
      4. Give your webhook a Title
      5. Copy and paste the URL for the POST Service into the URL field for your new webhook
      6. Adjust Status and SSL/TLS settings accordingly
      7. For triggers, make sure it is set to Repository:Push (this should be the default)
      8. What the service the webhook sends the event payload to does with said payload is up to the owner of that service.
      9. More info about event payloads can be found here 

[Chema Fernandez]

Hi @David Dansby 

Just a double check, if there is not a Services option under Workflow then I don't have to do anything, correct?

Please, find screenshot below to confirm.

[Pim]

@David Dansby Thanks for your response. Using the updated URL you provided there is no next value in the response. Please see screenshot below.

What would be the URL structure for requests to successive pages? I could perhaps make them myself (it should be only 4-5 pages).