Migrate users and groups from Jira to Bitbucket Data Center
Platform Notice: Data Center Only - This article only applies to Atlassian apps on the Data Center platform.
Note that this KB was created for the Data Center version of the product. Data Center KBs for non-Data-Center-specific features may also work for Server versions of the product, however they have not been tested. Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.
*Except Fisheye and Crucible
Summary
This article explains how to migrate users and groups from a Jira Data Center user directory to the Bitbucket Data Center internal directory. Since Jira Software Cloud cannot be used to manage your Bitbucket Data Center users, the existing users and groups configured in Jira Data Center must be moved to a supported platform.
Solution
Steps to Import Users: To import users from Jira to Bitbucket, please refer to this KB Article: Import users to Bitbucket from an external user directory | Bitbucket Data Center | Atlassian Support
Note: While adding users to Bitbucket Internal Directory, if you get the message “User <user_name> already exists.”, this implies that the user already exists with Bitbucket. The admin is advised to use their own discretion to determine what group memberships (While executing Step 5 or 6 in the following section) should be provided to such a user.
Steps to Import Groups:
The below queries were tested against a PostgreSQL database and may need to be altered to match the syntax of your specific database version/vendor.
Important note on database SQL queries
The database queries in this article are provided as examples only and are not covered by Atlassian Support. Atlassian cannot assist with translating, customizing, or troubleshooting these queries for any database management system (DBMS). For more information on what is covered by Atlassian Support, review our Atlassian Support Offerings page.
Always consult your local Database Administrator (DBA) before running any queries or making changes to your database.
For supported data extraction and troubleshooting, use the Bitbucket REST API. See the The Bitbucket Data Center REST API for details.
For groups and group memberships, please use the following procedure which is similar to the process for users. The SQL commands to fetch data should be run on Bitbucket Database when the same is connected to Jira User Directory.
Get the directory ID: In the below SQL query, replace <LDAP_directory_name> with your Jira User Directory Name and run the same to get the directory ID:
select id from cwd_directory where directory_name=<LDAP_directory_name>;Export ACTIVE groups from the required directory: In the following SQL Query, replace the <directory_id> with the Directory ID fetched in the previous step. This query fetches only the Active groups.Save the SQL query result .
select group_name from cwd_group where directory_id=<directory_id> and is_active='T';To export the user group memberships: In the following SQL Query, replace the <directory_id> with the Directory ID fetched in the first step. This query fetches only the Active members of the Active groups. Save the SQL query result. In the output, parent_name
will be the name of the group and child_name will be all the users belonging to that group.
select parent_name, child_name from cwd_membership mem, cwd_user u, cwd_group grp where mem.directory_id=<directory_id> and mem.child_id = u.id and mem.parent_id = grp.id and grp.is_active='T' and u.is_active='T';Disable the external user directory in Administration > User Directories. Please do not remove the same, only disable.
Create Groups and add Users using REST API: Once you have collected the data you can use to UI or make use of the following two REST API endpoints to create the groups and add users to the groups using the data extracted from the database. You could automate this by creating a script that reads from the extracted data and posts to Bitbucket:
REST API to create a new group in Bitbucket : The Bitbucket Data Center REST API
REST API to add users to a group in Bitbucket : The Bitbucket Data Center REST API
Create Groups and add Users using UI: You can also create groups and add users using the UI. Steps to do the same have been mentioned over : Users and groups | Bitbucket Data Center 10.2 | Atlassian Documentation
Note : While adding groups to Bitbucket Internal Directory, if you get the message “Group <group_name> already exists.” , this implies that the group name already exists with Bitbucket. The admin is advised to use their own discretion to determine what permissions should lie with such a group.
NOTE
Prior to adding groups from Jira to Bitbucket, make sure you have migrated the users to Bitbucket or the users are accessible by Bitbucket , else you may get the error
"No user named '<unaccessible_user>' was found"It is strongly recommended to back up the permissions on your Bitbucket instance before disabling the Jira User Directory. You can refer this documentation for the same: How to report on permissions in Bitbucket Data Center | Bitbucket Data Center | Atlassian Support
We also recommend backing up the entire Bitbucket data Center instance before proceeding with the steps above .
Please test this approach in a Test/Staging Environment prior to Production .
It is also highly recommended that you observe the Bitbucket instance at least for a week after the import is done and not remove the Jira External Directory from User Directories in Bitbucket Data Center, only keep it disabled.
In addition to the above, there are ways of editing the database directly in order to add users as well, but this is riskier and is not recommended.
Was this helpful?