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 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> Manage account
    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

Will become:

HTTPS

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

Will become:

HTTPS

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:

  2. Remove the origin designation using git remote rm origin as shown in the following example:

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

  4. Verifiy the new remote using the  git remote -v command as shown in the following example:

Change Git action URL's

Git actions URL's like this:

HTTP

Will have to change to this:

HTTPS

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

Will have to change to this:

HTTPS

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.

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!

24 Archived comments

    1. User avatar

      Anonymous

      You cannot change default page for your domain. You can only select either overview or JIRA web page.

      17 Jul 2012
  1. User avatar

    Anonymous

    Bitbucket could allow people to upload additional ssl certificates and chain them.

    Bitbucket chooses not to do so.

    06 Dec 2012
    1. User avatar

      manthony

      Please feel free to file an enhancement request for this.  Then, other people can vote up your feature request.

      07 Dec 2012
      1. User avatar

        Branko Wilhelm

        im using this service now over nginx reverse proxy: https://git.z-index.net

        08 Mar 2015
  2. User avatar

    Anonymous

    I expected that my custom domain, e.g. 'git.myname.com', will replace 'bitbucket.org/myname' in repository URLs. However, it turns out that it is merely an alias for 'bitbucket.org'. Now repos have the following URLs:

    git.myname.com/myname/reponame.git

    which is obviously redundant and not as convenient as the more convenient (which I expected)

    git.myname.com/reponame.git

    In fact, I struggle to see how the current basic domain aliasing scheme is useful. I expect my custom domain to point to the root of my account, not to the root of the whole BitBucket...

    16 Sep 2013
    1. User avatar

      Anthony Steiner

      There are allot of architectural reasons for this.  Namely; Bitbucket started out as Mercurial only... made it much easier to delegate repositories based on URLs.  Git has a different file structure architecture... and while the folks at Bitbucket and ultimately Atlassian did their best to accommodate the CNAME feature for both repositories, Git simply requires the user's name and repo to effectively connect.  Also, the CNAME is likely impossible to use if you're authenticating via SSH (which any security serious developer should) since it authenticates by the thumbprint of the certificate (usually influence by the url or IP address of the connecting security assertion) which will likely throw errors left and right.

      The CNAME feature is a legacy feature too many folks still rely on to remove entirely; but I imagine it will eventually be phased out.  If you're really hurting for the code to be git.myname.com you can install git on your server (assuming you have root access) and simply add the remote location on pushes.  This way bitbucket and your own repo will be in-sync with your source; your team can use the personalized address, AND you keep all the benefits of being on Bitbucket (community, wiki, issues, etc). 

      17 Sep 2013
      1. User avatar

        Anonymous

        Thanks for the reply, Anthony! What you're saying makes sense. It's actually simpler to use bitbucket.org instead of git.myname.com, which is what I ended up doing.

        17 Sep 2013
  3. User avatar

    Stephen Buergler

    hxxp://code.steinerd.org/ now redirects to crazy websites. I think the owner of the domain lost it.

    Edit:
    Something strange is going on. When I set my hosts file to point code.steinerd.org to a bitbucket server (131.103.20.167), requesting / on the server gives me https://bitbucket.org/ale_developsoulhxxp://code.steinerd.com/bitbucket-api-library/wiki/documentation/index.html gives me https://bitbucket.org/steinerd/bitbucket-api-library/wiki/Home. So even if the domain wasn't sending people to crazy places, bitbucket's servers are doing the wrong thing.

    Proof of me being sent to crazy websites:
    http://tools.pingdom.com/fpt/#!/ctJIL6/http://code.steinerd.org/
    http://tools.pingdom.com/fpt/#!/b7T9KG/http://code.steinerd.org/ 
    http://tools.pingdom.com/fpt/#!/chZ7Xl/http://code.steinerd.org/ 

    20 Jun 2014
    1. User avatar

      Anthony Steiner

      I recently moved VPS hosts, and the DNS was up in the air for a few days.  I just went into the control panel and clicked "save domain" on the Custom domain page, and flushed my DNS and the alias is working again.  

      That was really weird, but it was most definitely the DNS servers, not BitBucket. 

      20 Jun 2014
      1. User avatar

        Stephen Buergler

        whois says steinerd.org is owned by "Ivan Toplij"

        Here is a more recent test. The same type of stuff is happening:
        http://tools.pingdom.com/fpt/#!/DjZj1/http://code.steinerd.org/

         dig says the domain points directly to an ip address instead of being CNAMEed to bitbucket.org

        ;; ANSWER SECTION:
        code.steinerd.org. 2254 IN A 69.43.160.163

        I still think your domain is gone. : \
        good luck trying to get it back. Sorry.

        09 Jul 2014
        1. User avatar

          Anthony Steiner

          Oh, it was never steinerd.org, I only own steinerd.com 

          09 Jul 2014
          1. User avatar

            Stephen Buergler

            Hmm.. I see.. Well, https://web.archive.org/web/20130926151843/https://confluence.atlassian.com/display/BITBUCKET/Associate+an+existing+domain+with+an+account had a link to steinerd.org. Every other place in the wiki except for the link pointed to steinerd.com, which was two other places including the picture and excluding the comments section.

            I guess the real problem was a typo. Oops.

            09 Jul 2014
    1. User avatar

      Dan Stevens [Atlassian]

      Thank you for taking the time to comment and point this out. For the time being I've removed that example.

      20 Jun 2014
      1. User avatar

        Anthony Steiner

        There is a table with the same example just below it as well.  I don't want to have folks thinking my site represents BitBucket's hard work.  I just seem to be one of a few to get the CNAME working. 

        20 Jun 2014
        1. User avatar

          Dan Stevens [Atlassian]

          Thanks Anthony! I appreciate your efforts. I've updated the remaining portions of the document as well. (smile)

          21 Jun 2014
  4. User avatar

    Anthony Steiner

    CALLED IT! (tongue) 

    17 Apr 2015
  5. User avatar

    John Simpson

    Why are you disabling custom hostnames? And why was my first notification about this, a warning when I did a git push command?

    We have over 300 repos on our account, with literally thousands of places in those repos where our custom hostname is being used to reference cross-repo dependencies.

    Using a custom hostname allows us to NOT be locked into any specific hosting provider, and is the reason we were able to move all of our repos from another provider to Bitbucket over a weekend.

    I will now need to balance the SEVERAL WEEKS it will take to hunt down and change everyplace that our custom hostname appears in every repo, plus verify that the changes don't break our build processes, plus the knowledge that in doing so we are giving up the flexibility to move to another provider in a relatively painless manner, against the ONE DAY it would take to copy our repos to another hosting provider and change a DNS record.

    I strongly suggest you re-consider the decision to not allow custom hostnames anymore. At the very least, offer it as a paid-only option.

    Otherwise, there's a good chance you will lose our business, along with however many other people are in the same situation.

    17 Apr 2015
    1. User avatar

      Ike DeLorenzo [Atlassian]

      Hi John,

      We certainly understand that deprecating a feature in our product will affect customers.  In this case, those customers using Custom Domains (CNAMES) have been e-mailed individually, and warning notices (such as the one you saw) are now appearing in the both console, and in the Bitbucket web interface for accounts using the feature.  Customers using the feature will see these notifications for the next 60 days, and during this period requests will be forwarded to the correct location to give customers time to update URLs.

      We are removing this feature for two reasons: (1) There are security concerns around using CNAMES in this way, discussed and with an explanation from one of our senior Architects here.  (2) The feature has a very low user adoption.  We want to focus product efforts on highly requested features, and those we believe will be most appreciated by users – and keep those features performant, highly secure, and integrated.

      If you need more information on how to best update to accommodate CNAME deprecation, please contact us at support@bitbucket.com.  A real support engineer will actually get back to anyone needing help, paid user or not.  

      Ike DeLorenzo
      Product Manager
      Bitbucket 

      17 Apr 2015
      1. User avatar

        John Simpson

        I hadn't even thought about HTTP access. We only use SSH to access our repos, so non-encrypted traffic is not an issue.

        And now that I think about it...the SSH protocol doesn't have a way for the server to know what hostname is being used by the client. Which means that, even after you "disable CNAME support", our custom hostname will still point to the same set of IPs, and as long as the SSH service is still available, SSH access using our custom hostnames can't be "disabled".

        You may want to make it clear that what you are disabling is HTTP support for custom hostnames, and that SSH using custom hostnames will continue to work as it currently does.

        20 Apr 2015
        1. User avatar

          Anthony Steiner

          I'm inclined to agree with John's mindset on the topic.  Even if Atlassian disables Custom Domains (CNAME) support, Hostname-ed SSH connections should still resolve; however I wonder if there is some mechanism that allows for the authentication portion of it, because those keys usually follow a 'known_hosts' file on the authenticating machine, and if things don't match up; the connection will fall flat on its face. 

          20 Apr 2015
          1. User avatar

            John Simpson

            I just tried creating two brand new CNAMEs, one in the work domain and one in my personal domain. I was able to git clone one of my work-related repos using both hostnames. So unless they're planning on disabling SSH access entirely (which would, I suspect, elicit a much louder set of objections from their user base) I'm pretty sure that SSH access will continue to work, regardless of what they do to their web servers.

            The known_hosts file allows a client to verify a server's identity - basically if you've connected to a given hostname at least one time before, your client remembers the server's public host key, and can then tell if you're suddenly talking to a different server, because the server's host key will (presumably) be different. It has no bearing on whether or not the server decides to trust the client.

            20 Apr 2015
        1. User avatar

          Dan Stevens [Atlassian]

          Hello John Simpson and Anthony Steiner,

          What you suggest will, in fact, work. I just want to be clear that we will not be actively supporting running your custom domain through SSH which is why I did not mention it in the docs.

          Thanks for taking the time to comment. (smile)

          Dan Stevens

          21 Apr 2015
  6. User avatar

    Jason Gowans (Aerobatic LLC)

    FYI the Aerobatic add-on for Bitbucket supports multiple CNAMEs per web app. Implementation details of the add-on can be found on our blog post: http://bitbucket.aerobatic.com/blog/websites-for-bitbucket-powered-by-aerobatic.html. Cheers.

    18 Jun 2015
Powered by Confluence and Scroll Viewport