Associate an existing domain with an account

We have stopped allowing new custom domain entries using the DNS canonical name record (CNAME) process. Existing CNAME's will continue to function as expected while we phase out this feature.

We will be disabling the CNAME feature completely on July 1, 2015. If you have a CNAME enabled you will want to plan for impacts this will have for you, your team, and anyone else who is accessing the repositories owned by the team or account to make this transition.

Because we have stopped supporting CNAME's by July 1, 2015 you must change your custom domain URL's everywhere they are used to access your Bitbucket Cloud team, account, repositories, and any automated processes which access Bitbucket using the custom domain URL.

We've provided a set of examples to illustrate the process on this page.

Remove your custom domain

Before you remove your CNAME plan for changing the url references used to access the account and all it's repositories as shown in the following examples.

To remove your CNAME

  1. Do one of the following to access your team or account manage page:
    1. For an individual account: Click avatar > Bitbucket settings
    2. For a team: Click Teams>your team name then click Manage team.
  2. Click Custom domain.
  3. Click Remove Custom Domain.

Your Bitbucket team, account, and associated repositories will no longer be accessible using the custom domain URL.

Change all URL's to remove the custom domain

Change URL to access the account or team in Bitbucket

Removing the CNAME from your team or account will revert the URL used to access the team or account's overview and management pages.

This URL to access account or team overview pages:

HTTP
http://myurl.myteam.com 

Will become:

HTTPS
https://bitbucket.org/teamname
or 
https://bitbucket.org/accountname

Change the URL to access the repositories owned by the account or team

Removing the CNAME from your team or account will revert the URL used to access the team or account's repositories.

This URL to access repositories:

HTTP
http://myurl.myteam.com/web-development

Will become:

HTTPS
https://bitbucket.org/teamname/web-development
or 
https://bitbucket.org/accountname/web-development

Change Git remote origin

If you used the CNAME domain when you initially set up your local repositories you will have to remove the remote origin entry for each repository and replace it so that it points to the repository in Bitbucket using: bitbucket.org/teamname/repo-name.

  1. Check to see what your current remote is by switching to the directory containing your repository and using the git remote -v command. It should reveal your default fetch and push URL's similar to the following:

    $ git remote -v
    origin    https://username@myurl.myteam.com/web-development.git (fetch)
    origin    https://username@myurl.myteam.com/web-development.git (push)
  2. Remove the origin designation using git remote rm origin as shown in the following example:

    git remote rm origin
  3. Add the path to your remote using git remote add origin as shown in the following example:

    git remote add origin    https://username@bitbucket.org/teamname/web-development.git
  4. Verifiy the new remote using the  git remote -v command as shown in the following example:

    $ git remote -v
    origin    https://username@bitbucket.org/teamname/web-development.git (fetch)
    origin    https://username@bitbucket.org/teamname/web-development.git (push)

Change Git action URL's

Git actions URL's like this:

HTTP
git clone http://username@myurl.myteam.com/web-development.git

Will have to change to this:

HTTPS
git clone https://username@bitbucket.org/teamname/web-development.git

SSH and other processes

Modify all URL's to replace the CNAME URL (myurl.myteam.com) with the Bitbucket URL (bitbucket.org) including any SSH and automated or other processes accessing your Bitbucket repositories.

Change mercurial action URL's

Mercurial action URL's like this:

HTTP
hg clone http://username@myurl.myteam.com/web-development

Will have to change to this:

HTTPS
hg clone https://username@bitbucket.org/teamname/web-development

SSH and other processes

Modify all URL's to replace the CNAME URL (myurl.myteam.com) with the Bitbucket URL (bitbucket.org) including any SSH and automated or other processes accessing your Bitbucket repositories.

The information provided below is stored for archive purposes only.

  Install and CNAME FAQ information (deprecated)

Using a CNAME with Bitbucket will result in unencrypted http:// (not the https:// which Bitbucket uses) communication between your usersand the Bitbucket website. This means passwords and other potentially sensitive data will be sent in clear text.

You can alias an custom domain to your individual or team account page on Bitbucket using a DNS CNAME (canonical name record). A CNAME record is type of resource record in the Domain Name System (DNS). The CNAME record specifies that the domain name is an alias of another domain name.  This option of using a custom domain is available for all Bitbucket accounts both free and paid pricing plans.

To set up a CNAME, you must own the domain name you are aliasing.  For example, the custom domain  git.coolcode.com  has a domain name of coolcode.com . To alias your account in the  bitbucket.org  domain ( bitbucket.org/youraccountname ) to coolcode.com , you must own the coolcode.com domain. 

The DNS specification disallows CNAME records at the root of a site. So, if you own coolcode.com , do not associate your top level domain, coolcode.com , with your Bitbucket account. Instead, alias a subdomain such as git.coolcode.com or source.coolcode.com .

You can also host a static website directly from the contents of a Bitbucket repository, in which case the site name would be  youraccountname.bitbucket.org and the domain is  bitbucket.org .  If you want to learn how to host a static website, see Publishing a Website on Bitbucket Cloud.

How to set up a CNAME for your Bitbucket Account

To set up a CNAME, you must perform two procedures; one on your DNS hosting service and one on Bitbucket. 

On your DNS hosting service

The actual steps to configure a CNAME vary depending on the DNS provider you use.  You should consult the help for the service to find out the exact steps.

  1. Log into the domain control panel DNS administration for your domain name.
  2. Configure the domain name you want.
    In this example, the user had a DNS that required this type of configuration:

    NAME TYPE value
    example.mydomain.com CNAME bitbucket.org

    Keep in mind your DNS provider may ask you to configure this differently.  For example, notice that there are no http(s) or slashes in these settings.

On Bitbucket:

To avoid negative caching, create your CNAME entry before with your DNS hosting provider before proceeding.

  1. Log into the Bitbucket account you want to alias.
  2. Choose your avatar > Manage Account from the menu bar.
  3. Choose Custom domain from the left menu bar.
  4. Enter a Cname in the field provided.
    In this example you enter the following:
  5. Click Save domain
HTTPS and CNAMEs

Please note that accessing a Bitbucket account configured with a custom domain over HTTPS may result in security warnings from your browser.

The Bitbucket service can only serve one SSL certificate, and that certificate can only be associated with the bitbucket.org domain. When you access a CNAME over HTTPS, your browser will see that the certificate's domain doesn't match the address you've visited and presents a warning message. For this reason, we allow non-secure HTTP access to CNAMEs. However, if you don't mind the certificate warnings and you'd prefer to access your CNAME over an encrypted session, you can still use HTTPS.

For cloning, pushing, and pulling to repositories on CNAMEs, we recommend connecting directly to bitbucket.org over HTTPS or SSH to ensure your password is transmitted securely.

Frequently Asked Questions about CNAMES
  • Can I get SSL support for my customer domain? 
    Bitbucket doesn't support installation of custom SSL certificates on our systems. As a result, we cannot support SSL on custom domains. We recommend using the website directly via bitbucket.org to ensure your privacy remains protected at all times if this is a concern for you. 

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport