Connecting Bitbucket Server to Jira for user management
This page does not apply to Jira Software Cloud; you can't use Jira Software Cloud to manage your Bitbucket Data Center and Server users.
You can connect Bitbucket to an existing Atlassian Jira Software instance to delegate Bitbucket user and group management, and authentication. Bitbucket provides a "read-only" connection to Jira Software for user management. This means that users and groups, fetched from Jira Software, can only be modified or updated in that Jira Software server, rather than in Bitbucket.
Choose this option, as an alternative to Atlassian Crowd, for simple configurations with a limited number of users. Note that Bitbucket can only connect to an instance running Jira Software 4.3 or later.
Connecting Bitbucket and Jira Software is a 3-step process:
1. Set up Jira Software to allow connections from Bitbucket
2. Set up Bitbucket to connect to Jira Software
3. Set up Bitbucket users and groups in Jira Software
Also on this page:
You need to be an administrator in Jira Software and a system administrator in Bitbucket to perform the following tasks.
Managing 500+ users across Atlassian products?
Find out how easy, scalable and effective it can be with Crowd!
See centralized user management.
1. Setup Jira Software to allow connections from Bitbucket
- Log in as a user with the 'Jira Software Administrators' global permission.
- For Jira 4.3.x, select Other Application from the 'Users, Groups & Roles' section of the 'Administration' menu.
For later versions, choose
> User management > Jira User Server. - Click Add Application.
- Enter the application name (case-sensitive) and password that Bitbucket will use when accessing Jira Software.
- Enter the IP address of your Bitbucket instance. Valid values are:
- A full IP address, e.g.
192.168.10.12. - A wildcard IP range, using CIDR notation, e.g.
192.168.10.1/16. For more information, see the introduction to CIDR notation on Wikipedia and RFC 4632.
- A full IP address, e.g.
- Click Save.
- Define the directory order, on the 'User Directories' screen, by clicking the blue up- and down-arrows next to each directory. The directory order has the following effects:
- The order of the directories is the order in which they will be searched for users and groups.
- Changes to users and groups will be made only in the first directory where the application has permission to make changes.
2. Setup Bitbucket to connect to Jira Software
- Log in to Bitbucket as a user with 'Admin' permission.
- In the Bitbucket administration area click User Directories (under 'Accounts').
- Click Add Directory and select Atlassian Jira.
- Enter settings, as described below.
- Test and save the directory settings.
- Define the directory order, on the 'User Directories' screen, by clicking the arrows for each directory. The directory order has the following effects:
- The order of the directories is the order in which they will be searched for users and groups.
- Changes to users and groups will be made only in the first directory where the application has permission to make changes.
3. Set up Bitbucket users and groups in Jira Software
In order to use Bitbucket, users must be a member of the Bitbucket Server-users group or have Bitbucket global permissions. Follow these steps to configure your Bitbucket groups in Jira Software:
- Add the
bitbucket-usersandbitbucket-administratorsgroups in Jira Software. - Add your own username as a member of both of the above groups.
- Choose one of the following methods to give your existing Jira Software users access to Bitbucket:
- Option 1: In Jira Software, find the groups that the relevant users belong to. Add those groups as members of one or both of the above Bitbucket groups.
- Option 2: Log in to Bitbucket using your Jira Software account and go to the administration area. Click Global permissions (under 'Accounts'). Assign the appropriate permissions to the relevant Jira Software groups. See Global permissions.
Connecting Atlassian Bitbucket to Jira Software for user management is not sufficient, by itself, to allow your users to log in to Bitbucket. You must also grant them access to Bitbucket by using one of the above 2 options.
We recommend that you use groups instead of individual accounts when granting permissions. However, be careful not to add more users to those groups that your Bitbucket license allows. If the license limit is exceeded, your developers will not be able to push commits to repositories, and Bitbucket will display a warning banner. See this FAQ.
See also this information about deleting users and groups in Bitbucket.
Server settings
Setting | Description |
|---|---|
Name | A meaningful name that will help you to identify this Jira server in the list of directory servers. Examples:
|
Server URL | The web address of your Jira server. Examples:
|
Application Name | The name used by your application when accessing the Jira server that acts as user manager. Note that you will also need to define your application to that Jira server, via the 'Other Applications' option in the 'Users, Groups & Roles' section of the 'Administration' menu. |
Application Password | The password used by your application when accessing the Jira server that acts as user manager. |
Jira Software server permissions
Setting | Description |
|---|---|
Read Only | The users, groups and memberships in this directory are retrieved from the Jira server that is acting as user manager. They can only be modified via that JIRA server. |
Advanced settings
Setting | Description |
|---|---|
Enable Nested Groups | Enable or disable support for nested groups. Before enabling nested groups, please check to see if nested groups are enabled on the JIRA server that is acting as user manager. When nested groups are enabled, you can define a group as a member of another group. If you are using groups to manage permissions, you can create nested groups to allow inheritance of permissions from one group to its sub-groups. |
| Enable Incremental Synchronization | Enable or disable incremental synchronization. Only changes since the last synchronization will be retrieved when synchronizing a directory. |
Synchronization Interval (minutes) | Synchronization is the process by which the application updates its internal store of user data to agree with the data on the directory server. The application will send a request to your directory server every x minutes, where 'x' is the number specified here. The default value is 60 minutes. |