Use the SSH protocol with Bitbucket Cloud

You can use either secure hypertext transport protocol (HTTPS) or secure shell (SSH) to connect to Bitbucket Cloud. HTTPS requires you to enter a username/password each time you connect to the Bitbucket server, for example, when you push your changes. HTTPS is suitable for situations where you work with Bitbucket infrequently and make few code changes. However, if you do most of your coding with a Bitbucket hosted repository, you'll want to set up a SSH connection. After you configure SSH, Bitbucket no longer requires you to authenticate each remote communication with a username/password combination. This page contains the following topics:

How SSH and Bitbucket work together

To use SSH with Bitbucket, you create an SSH identity. An identity consists of a private and a public key which together are a key pair. The private key resides on your local computer and the public you upload to your Bitbucket account. Once you upload a public key to your account, you can use SSH to connect with repositories you own and repositories owned by others, provided those other owners give your account permissions. By setting up SSH between your local system and the Bitbucket server, your system uses the key pair to automate authentication; you won't need to enter your password each time you interact with your Bitbucket repository.

There are a few important concepts you need when working with SSH identities and Bitbucket.

  • You cannot reuse an identity's public key across accounts. If you have multiple Bitbucket accounts, you must create multiple identities and upload their corresponding public keys to each individual account. 
  • You can associate multiple identities with a Bitbucket account. You would create multiple identities for the same account if, for example, you access a repository from a work computer and a home computer. You might create multiple identities if you wanted to execute DVCS actions on a repository with a script – the script would use a public key with an empty passphrase, allowing it to run without human intervention.
  • RSA (R. Rivest, A. Shamir, L. Adleman are the originators) and digital signature algorithm (DSA) are key encryption algorithms. Bitbucket supports both types of algorithms. You should create identities using whichever encryption method is most comfortable and available to you.

If you have multiple identities, you'll need a SSH authentication agent program on your local system. This program runs in the background. You load all your keys into the agent and it manages the authentication for you. In a Windows environment, a common authentication agent is Pageant. In Mac OSX and Linux systems, ssh-agent is more common.

Deciding if you need a single or multiple identities

You only have to create two identities (keys) if you have two different Bitbucket accounts. The typical use case is the programmer who has a work-related Bitbucket account and a personal Bitbucket account.  Each account must have its own SSH key.  

SSH keys give you identity-based authentication. This means you can use the same identity from as many different systems as you like and connect to as many services with that identity.  Whether you should do this depends on how security conscious you are or need to be.

You should definitely have separate private keys per origin. That means there is a single copy of each private key (not counting backups). It's ok to use the same private key between closely related machines, such as situations in which where breaking into one machine basically gives you access to the other (for example if they're in each other's shosts.equiv). Don't use the same private key to log in from different networks (e.g. home and work), never share a private key between two users, and never share a private key between a laptop and any other machine.

If you aren't concerned about securing an identity, you can copy your identity to multiple machines. If you are concerned, or if you have multiple Bitbucket accounts, you should create multiple identities.

Single or multiple identity setup

If you have not set up SSH already, you can use these pages:

The following pages provide information on configuring multiple identities:

The section on Windows with TortoiseHG assumes you have installed PuTTy. If you have problems, please try to resolve your problems using our Troubleshoot SSH Issues page.

Repository URL formats by connection protocol

The URL you use to access a repository depends on the connection protocol (HTTPS or SSH) and the DVCS program. The following table shows the URL format for each case Bitbucket supports:

  SSH URL format HTTPS URL format
Mercurial ssh://




In the SSH format, the accountname appears after or In HTTPS format, the accountname before or

Bitbucket displays repository-specific URLs for both Git and Mercurial on your repository Overview page.

Known host or Bitbucket's public key fingerprints

Each server that allows connection over the SSH provides its own public key to the connecting client. SSH stores the key in a known hosts list. In Mac OSX and Linux this list is in a ~/.ssh/known_hosts file. On Windows, PuTTYgen stores the information in the HKEY_CURRENT_USER\SoftWare\SimonTatham\PuTTY\SshHostKeys registry key. Each time your client reconnects SSH checks the server's identity against your known hosts just as the host is checking your identity. This two-way mechanism prevents man-in-the-middle attacks.

Bitbucket hosts only allow Git and Mercurial to make SSH connections. The first time you access Bitbucket using the SSH URL, your SSH client checks to see if the Bitbucket host is a known host. If the host is not in your ~/.ssh/known_hosts file SSH warns you that it is adding the Bitbucket host to known hosts:

$ hg clone ssh:// testkey
The authenticity of host ' (' can't be established.
RSA key fingerprint is 97:8c:1b:f2:6f:14:6b:5c:3b:ec:aa:46:46:74:7c:40.
Are you sure you want to continue connecting (yes/no)? 

If you view the contents of known hosts is stored you find the actual key is stored in a base64 encoded format:, ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAubiN81eDcafrgMeLzaFPsw2kNvEcqTKl/VqLat/MaB33pZy0y3rJZtnqwR2qOOvbwKZYKiEO1O6VqNEBxKvJJelCq0dTXWT5pbO2gDXC6h6QDXCaHo6pOHGPUy+YBaGQRGuSusMEASYiWunYN0vCAI8QaXnWMXNMdFP3jHAJH0eDsoiGnLPBlBp4TNm6rYI74nMzgz3B9IikW4WVK+dc8KZJZWYjAuORU3jc1c/NPskD2ASinf8v3xnfXeukU0sJ5N6m5E8VLjObPEO+mN2t/FZTMZLiFqPWc/ALSqnMnnhwrNi2rbfg/rd/IpL8Le3pSBne8+seeFVBoGqzHM9yXw==

Technically, you should record the server's public host key before connecting to it for the first time. Depending on the security protocols in your network, the system administrator may maintain a centrally located list of approved known hosts. The public key fingerprints for the Bitbucket server are:

97:8c:1b:f2:6f:14:6b:5c:3b:ec:aa:46:46:74:7c:40 (RSA)
35:ee:d7:b8:ef:d7:79:e2:c6:43:9e:ab:40:6f:50:74 (DSA)

To get the format suitable for storage in the known hosts, you can use the following ssh-keyscan command:

$ ssh-keyscan -t rsa
# SSH-2.0-OpenSSH_5.3 ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAubiN81eDcafrgMeLzaFPsw2kNvEcqTKl/VqLat/MaB33pZy0y3rJZtnqwR2qOOvbwKZYKiEO1O6VqNEBxKvJJelCq0dTXWT5pbO2gDXC6h6QDXCaHo6pOHGPUy+YBaGQRGuSusMEASYiWunYN0vCAI8QaXnWMXNMdFP3jHAJH0eDsoiGnLPBlBp4TNm6rYI74nMzgz3B9IikW4WVK+dc8KZJZWYjAuORU3jc1c/NPskD2ASinf8v3xnfXeukU0sJ5N6m5E8VLjObPEO+mN2t/FZTMZLiFqPWc/ALSqnMnnhwrNi2rbfg/rd/IpL8Le3pSBne8+seeFVBoGqzHM9yXw==

SSH on Port 443

Some network administrators block outgoing SSH connections on port 22.  If your network blocks this port, Bitbucket provides an alternate hostname and port combination you can use.  The host supports SSH over port 443. Port 443 is typically used for HTTPS and administrator typically leave it open for outbound web browsing.  If you are blocked, you can use these URLs.

  Alternate SSH URL format
Mercurial ssh://
Git ssh://

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

19 Archived comments

  1. User avatar


    % hg --repository D:\LMTEST push --force ssh://[MYID]/[myRepo]
    pushing to ssh://[MYID]/[myRepo]
    remote: Looking up host ""
    remote: Connecting to port 22
    remote: We claim version: SSH-2.0-PuTTY_Local:_Feb__4_2012_13:00:04
    remote: Failed to connect to Network error: Connection timed out
    remote: Connecting to port 22
    remote: Failed to connect to Network error: Connection timed out
    remote: Network error: Connection timed out
    no suitable response from remote hg


    how to fix it?

    11 Apr 2013
  2. User avatar


    The issue for re-open SSH port to 443 has been created the 2012-03-28.**

    The demand it will be achieved?

    05 Jun 2013
    1. User avatar


      Le travail n'a pas été fixée. S'il vous plaît regarder la question.

      06 Jun 2013
  3. User avatar

    Erik Stainsby

    It would be nice to see an example here of how to use git clone to localize a particular branch - Example use case: I've messed up my local repos, and the tip of the develop branch on bitbucket is the commit I want to reset to.

    06 Jun 2013
    1. User avatar


      We have documentation on branching Branching a Repository. Documentation on fixing specific problems is, well, a difficult information design issue as Git is complex and many things can go wobbly.  

      06 Jun 2013
  4. User avatar


    For extra security you could deploy DNSSEC for the domain and use SSHFP records for the key fingerprint.

    11 Sep 2013
  5. User avatar

    Diego Alvarez Zuluaga

    Tks so much for SSH on port 443

    I have this In my ~/.gitconfig in order to always use SSH (big grin)

    Remember to change d1egoaz with your bitbucket username


    08 Jan 2014
  6. User avatar


    If you are using a recent version of OpenSSH, you may have host hashing enabled, so you won't see the "" entry as-is in known_hosts.  Instead, you can do this to see if it's in known_hosts:

    ssh-keygen -H -F

    This searches for the hashed host name in known_hosts. You can then pipe the output into grep to search for the bitbucket SSH public key listed on this page to confirm.


    15 Jan 2014
  7. User avatar

    Colin Richardson

    Can someone explain to me the reason of tying the accountname to the remote url at the start? This seems a completely unnecessary part since the username would be supplied via the standard https auth and incorrectly states the account name as the repoUsers name? Otherwise you are telling people to access MyOrg/Repo2.git you have to put in when they would actually need to put in though as I have said at the start, having the account name as part of the url at all just seems plain wrong and should just be simply and let https handle the account name.

    27 Oct 2014
    1. User avatar

      Erik van Zijst [Atlassian]

      having the account name as part of the url at all just seems plain wrong and should just be simply and let https handle the account name.

      You're right that git/hg will prompt for credentials where necessary, but the reason we're adding your logged-in username to the URL is because some people have multiple accounts (typically personal vs work) and not all of their accounts may have access to the repo they're trying to clone, which may lead to confusion when they get a 401 while they can see the repo just fine in the browser.

      A related, more subtle issue is that a repo may be public, meaning you'd not be prompted for credentials during cloning. However, you then get into trouble pushing changes back up.

      So while we could certainly drop the username from the clone URL, we have it in there to minimize friction.

      28 Oct 2014
      1. User avatar

        Colin Richardson

        If you have multiple accounts, you just type in the credentials of what ever account that one relates to. Putting in the username in the url does not change that fact. It could even hinder ease of use if someone clones with 1 account, and then things change (as life always does) and he wishes to push with another. Same with pulling a public repo, and then trying to push back to it. You will STILL have to type in your credentials if your account name is in the url or not. And again, return to scenario 1. Having the account name in url would not lower multiple account errors, just annoy people. "Oh, whats the url to the repo", copy/paste, Done.. Now its "Oh whats the url to the repo", copy/paste, "url doesn't work", oh, sorry, remove my username from the start with the @ sign and add your username in there now"... 

        28 Oct 2014
      1. User avatar

        Colin Richardson

        Oh, Never mind, I found it works if you don't put that in at all, much easier. Just be easier if you don't put in unnecessary stuff by default.

        28 Oct 2014
  8. User avatar

    Jay McDonald

    I am having trouble getting my repo on my webserver to connect via a git pull. as a diagnostic, I have also tried:

    ssh -Tv

    Which gave me:
    OpenSSH_5.3p1, OpenSSL 1.0.1e-fips 11 Feb 2013
    debug1: Connecting to [] port 22.
    debug1: connect to address port 22: Connection refused
    debug1: Connecting to [] port 22.
    debug1: connect to address port 22: Connection refused
    ssh: connect to host port 22: Connection refused

    I tried using this as the remote address:[username]/[reponame] (with user and repo names appropriately substituted)

    And that gives me:

    ssh: connect to host port 22: Connection refused
    fatal: The remote end hung up unexpectedly


    I'm at a loss

    29 Oct 2014
  9. User avatar

    Jay McDonald

    Well, after hosing 24 hrs on this, I discovered the issue. My web host had botched their cPanel instantiation :\

    29 Oct 2014
    1. User avatar

      Dan Stevens [Atlassian]

      Hey Jay,

      Apologies for not getting back to you on this. I'm glad you found a solution. If you have the desire (and time) to give me a quick primer on how you debugged, or any quick tips I'd be happy to hear and possibly add to a troubleshooting page. 

      Thanks again for taking the time to comment.

      Happy coding,


      30 Oct 2014
  10. User avatar

    Jay McDonald


    I was surprised to have it not work, because the normal setup had always worked with this webhost. After trying the things I listed, plus a few tips from others, I just never got it to work. I finally moved over to an identical hosting package created with the same provider on the same day, and tried it there. The normal setup worked on the first try. I concluded that they had just botched their deployment on the one package, since both packages were new, and I was just starting to get them set up. (and every other package I have had with these guys always worked in the normal way).


    30 Oct 2014
    1. User avatar

      Dan Stevens [Atlassian]

      Ah, good to know. Thanks so much for the follow up. (smile)


      30 Oct 2014
  11. User avatar

    Wonho Park

    I can`t use a Bitbucket on jenkins 

     I used id_rsa key on jenkins and key on bitbucket.

    but i can not connect to Bitbucket from jenkins 

    plz somebody help me about "status code 128"


    Failed to connect to repository : Command "usr/bin/git -c core.askpass=true ls-remote -h HEAD" returned status code 128:
    stderr: Permission denied (publickey). 
    fatal: Could not read from remote repository.

    Please make sure you have the correct access rights
    and the repository exists.


    19 May 2015
    1. User avatar

      Erik van Zijst [Atlassian]

      Happy to help out if you email us your repo and account details at

      20 May 2015
Powered by Confluence and Scroll Viewport