2020-10-29 15:09:12 +00:00
---
2022-05-13 03:08:13 +00:00
stage: Manage
group: Authentication and Authorization
2020-11-26 06:09:20 +00:00
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-10-29 15:09:12 +00:00
---
2021-09-28 09:11:19 +00:00
# Integrate your GitLab server with Bitbucket Cloud **(FREE SELF)**
2015-02-18 21:42:52 +00:00
2021-08-20 09:09:16 +00:00
You can set up Bitbucket.org as an OAuth 2.0 provider to use your Bitbucket.org
account credentials to sign in to GitLab. You can also import your projects from
2016-08-30 15:52:14 +00:00
Bitbucket.org.
2015-02-18 21:42:52 +00:00
2020-11-16 18:09:15 +00:00
- To use Bitbucket.org as an OmniAuth provider, follow the
[Bitbucket OmniAuth provider ](#bitbucket-omniauth-provider ) section.
2016-08-30 13:42:40 +00:00
- To import projects from Bitbucket, follow both the
[Bitbucket OmniAuth provider ](#bitbucket-omniauth-provider ) and
[Bitbucket project import ](#bitbucket-project-import ) sections.
2015-02-18 21:42:52 +00:00
2016-08-30 13:42:40 +00:00
## Bitbucket OmniAuth provider
To enable the Bitbucket OmniAuth provider you must register your application
2020-11-16 18:09:15 +00:00
with Bitbucket.org. Bitbucket generates an application ID and secret key for
2016-08-30 13:42:40 +00:00
you to use.
2015-02-18 21:42:52 +00:00
2021-02-25 00:11:24 +00:00
WARNING:
To help prevent an [OAuth 2 covert redirect ](https://oauth.net/advisories/2014-1-covert-redirect/ )
vulnerability in which users' GitLab accounts could be compromised, append `/users/auth`
to the end of the Bitbucket authorization callback URL.
2019-07-11 15:21:26 +00:00
1. Sign in to [Bitbucket.org ](https://bitbucket.org ).
1. Navigate to your individual user settings (**Bitbucket settings**) or a team's
settings (**Manage team**), depending on how you want the application registered.
It does not matter if the application is registered as an individual or a
team, that is entirely up to you.
2020-11-16 18:09:15 +00:00
1. In the left menu under **Access Management** , select **OAuth** .
2019-07-11 15:21:26 +00:00
1. Select **Add consumer** .
1. Provide the required details:
2020-11-16 18:09:15 +00:00
- **Name:** This can be anything. Consider something like `<Organization>'s GitLab`
or `<Your Name>'s GitLab` or something else descriptive.
2021-12-03 03:14:42 +00:00
- **Application description:** Optional. Fill this in if you wish.
2020-11-16 18:09:15 +00:00
- **Callback URL:** (Required in GitLab versions 8.15 and greater)
The URL to your GitLab installation, such as
2021-02-25 00:11:24 +00:00
`https://gitlab.example.com/users/auth` .
2020-11-16 18:09:15 +00:00
Leaving this field empty
[results in an `Invalid redirect_uri` message ](https://confluence.atlassian.com/bitbucket/oauth-faq-338365710.html ).
- **URL:** The URL to your GitLab installation, such as `https://gitlab.example.com` .
2019-07-11 15:21:26 +00:00
2020-11-16 18:09:15 +00:00
1. Grant at least the following permissions:
2019-07-11 15:21:26 +00:00
2020-03-24 03:09:28 +00:00
```plaintext
2019-07-11 15:21:26 +00:00
Account: Email, Read
Projects: Read
Repositories: Read
Pull Requests: Read
Issues: Read
Wiki: Read and Write
```
![Bitbucket OAuth settings page ](img/bitbucket_oauth_settings_page.png )
1. Select **Save** .
2020-11-16 18:09:15 +00:00
1. Select your newly created OAuth consumer, and you should now see a **Key** and
**Secret** in the list of OAuth consumers. Keep this page open as you continue
2019-07-11 15:21:26 +00:00
the configuration.
![Bitbucket OAuth key ](img/bitbucket_oauth_keys.png )
1. On your GitLab server, open the configuration file:
2020-03-24 03:09:28 +00:00
```shell
2019-07-11 15:21:26 +00:00
# For Omnibus packages
sudo editor /etc/gitlab/gitlab.rb
# For installations from source
sudo -u git -H editor /home/git/gitlab/config/gitlab.yml
```
1. Add the Bitbucket provider configuration:
For Omnibus packages:
```ruby
gitlab_rails['omniauth_providers'] = [
{
2021-11-19 09:13:48 +00:00
name: "bitbucket",
# label: "Provider name", # optional label for login button, defaults to "Bitbucket"
app_id: "BITBUCKET_APP_KEY",
app_secret: "BITBUCKET_APP_SECRET",
url: "https://bitbucket.org/"
2019-07-11 15:21:26 +00:00
}
]
```
For installations from source:
```yaml
omniauth:
enabled: true
providers:
- { name: 'bitbucket',
2021-11-19 09:13:48 +00:00
# label: 'Provider name', # optional label for login button, defaults to "Bitbucket"
2019-07-11 15:21:26 +00:00
app_id: 'BITBUCKET_APP_KEY',
app_secret: 'BITBUCKET_APP_SECRET',
url: 'https://bitbucket.org/' }
```
Where `BITBUCKET_APP_KEY` is the Key and `BITBUCKET_APP_SECRET` the Secret
from the Bitbucket application page.
1. Save the configuration file.
2021-01-06 03:10:22 +00:00
1. For the changes to take effect, [reconfigure GitLab ](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure )
if you installed using Omnibus GitLab, or [restart ](../administration/restart_gitlab.md#installations-from-source )
if you installed from source.
2015-02-18 21:42:52 +00:00
2020-11-16 18:09:15 +00:00
On the sign-in page there should now be a Bitbucket icon below the regular
2022-05-25 15:08:05 +00:00
sign-in form. Select the icon to begin the authentication process. Bitbucket asks
2020-11-16 18:09:15 +00:00
the user to sign in and authorize the GitLab application. If successful, the user
is returned to GitLab and signed in.
2015-02-18 21:42:52 +00:00
## Bitbucket project import
2020-11-16 18:09:15 +00:00
After the above configuration is set up, you can use Bitbucket to sign into
2020-04-06 12:10:44 +00:00
GitLab and [start importing your projects ](../user/project/import/bitbucket.md ).
2015-02-18 21:42:52 +00:00
2018-07-10 10:50:17 +00:00
If you want to import projects from Bitbucket, but don't want to enable signing in,
2022-05-11 15:07:26 +00:00
you can [disable Sign-Ins in the Admin Area ](omniauth.md#enable-or-disable-sign-in-with-an-omniauth-provider-without-disabling-import-sources ).