Set up SSH for Git

If you came to this page because you don't have SSH set up, then you have been using the secure hypertext transfer protocol (HTTPS) to communicate between your local system and Bitbucket. When you use HTTPS, you authenticate (supply a username and password) each time you take an action that requires a connection with Bitbucket. Who wants to do that? This page shows you how to use secure shell (SSH) to communicate with the Bitbucket server and avoid having to manually type a password all the time.

Set up SSH

Setting up an SSH identity can be prone to error. Allow yourself some time, perhaps as much as an hour depending on your experience, to complete this page. If you run into issues, check out Troubleshoot SSH Issues for extra information that may help you along. You can even skip this whole page and continue to use HTTPS if you want.

The following sections cover how to set up SSH for Git.

  Set up SSH for Windows

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.

Step 1. Ensure you have an SSH client installed

SSH should be included with the version of Git you installed. To make sure, do the following to verify your installation:

  1. From the Git Bash window, enter the following command to verify that SSH client is available:

    $ ssh -v
    OpenSSH_4.6p1, OpenSSL 0.9.8e 23 Feb 2007
    usage: ssh [-1246AaCfgkMNnqsTtVvXxY] [-b bind_address] [-c cipher_spec]
    [-D [bind_address:]port] [-e escape_char] [-F configfile]
    [-i identity_file] [-L [bind_address:]port:host:hostport]
    [-l login_name] [-m mac_spec] [-O ctl_cmd] [-o option] [-p port]
    [-R [bind_address:]port:host:hostport] [-S ctl_path]
    [-w local_tun[:remote_tun]] [user@]hostname [command]

    If you have ssh installed, the terminal returns version information.

    If you don't have ssh installed, install it now with your package manager.

  2. List the contents of your ~/.ssh directory.
    If you have not used SSH on Git Bash yet, you might see something like this:

    $ ls -a ~/.ssh
    ls: /c/Users/emmap1/.ssh: No such file or directory

    If you have a default identity already, you'll see two id_* files:

    $ ls -a ~/.ssh
    .    ..    id_rsa    id_rsa.pub  known_hosts

    In this case, the default identity uses RSA encryption (id_rsa.pub). If you want to use an existing default identity for your Bitbucket account, skip the next section and go to create a config file.

Step 2. Set up your default identity

By default, the system adds keys for all identities to the /Users/<yourname>/.ssh directory. The following procedure creates a default identity.

  1. Open a terminal in your local system.
  2. Enter ssh-keygen at the command line. 
    The command prompts you for a file to save the key in:

    $ ssh-keygen
    Generating public/private rsa key pair.
    Enter file in which to save the key (/c/Users/emmap1/.ssh/id_rsa):
  3. Press enter to accept the default key and path, /c/Users/<yourname>/.ssh/id_rsa, or you can create a key with another name.
    To create a key with a name other than the default, specify the full path to the key. For example, to create a key called my-new-ssh-key, you would enter a path like this at the prompt:

    $ ssh-keygen
    Generating public/private rsa key pair.
    Enter file in which to save the key (/c/Documents and Settings/emmap1/.ssh/id_rsa): /c/Users/emmap1/My Documents/keys/my-new-ssh-key
  4. Enter and renter a passphrase when prompted.
    Unless you need a key for a process such as script, you should always provide a passphrase. 
    The command creates your default identity with its public and private keys. The whole interaction looks similar to the following: 

    $ ssh-keygen
    Generating public/private rsa key pair.
    Enter file in which to save the key (/c/Users/emmap1/.ssh/id_rsa):
    Created directory '/c/Users/emmap1/.ssh'.
    Enter passphrase (empty for no passphrase):
    Enter same passphrase again:
    Your identification has been saved in /c/Users/emmap1/.ssh/id_rsa.
    Your public key has been saved in /c/Users/emmap1/.ssh/id_rsa.pub.
    The key fingerprint is: e7:94:d1:a3:02:ee:38:6e:a4:5e:26:a3:a9:f4:95:d4 emmap1@EMMA-PC
  5. List the contents of ~/.ssh to view the key files.
    You should see something like the following:

    $ ls ~/.ssh
    id_rsa id_rsa.pub

    The command created two files, one for the public key (for example id_rsa.pub) and one for the private key (for example, id_rsa).

Step 3. Create a SSH config file

  1. Using your favorite text editor, create a new file (at ~/.ssh/config) or edit the file if it already exists.

  2. Add an entry to the configuration file using the following format:

    Host bitbucket.org
     IdentityFile ~/.ssh/<privatekeyfile>

    The second line is indented. That indentation (a single space) is important, so make sure you include it. The second line is the location of your private key file.  If you are following along with these instructions, enter id_rsa for <privatekeyfile>.

    When you are done editing, your configuration looks similar to the following:

    Host bitbucket.org
     IdentityFile ~/.ssh/id_rsa
  3. Save and close the file.
  4. Restart the GitBash terminal.

Step 4. Update your .bashrc profile file

It is a good idea to configure your GitBash shell to automatically start the agent when you launch GitBash. The .bashrc file is the shell initialization file. It contains commands that run each time your GitBash shell starts. You can add commands to the .bashrc file that start the agent when you start GitBash. The folks at GitHub have developed a nice script for this (their script was developed from a post by Joseph M. Reagle Jr. from MIT on the cygwin list). To start the agent automatically, do the following.

  1. Start GitBash.
  2. Edit your ~/.bashrc file.

    If you don't have a .bashrc file you can create the file using your favorite text editor. Keep in mind the file must be in your ~ (home) directory and must be named exactly . bashrc .
  3. Add the following lines to the file:

    Chrome and Opera introduce ASCII \xa0 (non-breaking space characters) on paste that can appear in your destination file. If you copy and paste the lines below, copy from another browser to avoid this problem.

  4. Save and close the file.
  5. Close GitBash, then reopen GitBash.
  6. The system prompts you for your passphrase:

    Welcome to Git (version 1.7.8-preview20111206)
    Run 'git help git' to display the help index.
    Run 'git help <command>' to display help for specific commands.
    Enter passphrase for /c/Documents and Settings/manthony/.ssh/id_rsa:
  7. Enter your passphrase.
    After accepting your passphrase, the system displays the command shell prompt. 
  8. Verify that the script identity added your identity successfully by querying the SSH agent:

    $ ssh-add -l
    2048 0f:37:21:af:1b:31:d5:cd:65:58:b2:68:4a:ba:a2:46 /Users/manthony/.ssh/id_rsa (RSA)

After you install your public key to Bitbucket, having this script should prevent you from having to enter a password each time you push or pull a repository from Bitbucket.

Step 5. Install the public key on your Bitbucket account

  1. From Bitbucket, choose  avatar > Manage Account from the application menu. 
    The system displays the Account settings page.
  2. Click SSH keys.
    The SSH keys page displays. It shows a list of any existing keys. Then, below that, a dialog for labeling and entering a new key.
  3. In your terminal window, cat the contents of the public key file by entering the following:

    $ cat ~/.ssh/id_rsa.pub
  4. Select and copy the key output in the clipboard.
    If you have problems with copy and paste, you can open the file directly with Notepad. Select the contents of the file (just avoid selecting the end-of-file character).

  5. Back in your browser, enter a Label for your new key, for example, Default public key.

  6. Paste the copied public key into the SSH Key field.
  7. Press Add key.
    The system adds the key to your account. Bitbucket sends you an email to confirm addition of the key.
  8. Return to the terminal window and verify your configuration by entering the following command.

    $ ssh -T git@bitbucket.org

    The command message tells you which Bitbucket account can log in with that key.

    conq: logged in as tutorials.
    You can use git or hg to connect to Bitbucket. Shell access is disabled.
  9. Verify that the command returns your account name.

      Click if you got a permission denied (publickey) message.

    The command tests your connection to Bitbucket as a Git user. It first sees if your SSH Agent has an identity loaded. The command then checks if that private key matches a public key for an existing Bitbucket account. You might have either problem.

    To make sure your identity is loaded, enter the following command:

    $ ssh-add -l

    If the identity isn't loaded, check your work in Step 5 above. If it is loaded, try reinstalling your public key on your Bitbucket account. 

    Still having troubles? You can try our Troubleshoot SSH Issues page or email support@bitbucket.org.

Step 6. Configure your repository to use the SSH protocol

The URL you use for a repo depends on which protocol you are using, HTTPS or SSH. The Clone button of the BitbucketSpaceStation repository has a quick way for you to see these URLS.

Experiment for a moment, clicking back and forth between the SSH and the HTTPS protocol links to see how the URLs differ. The table below shows the format based on protocol.

SSH URL format

git@bitbucket.org :< accountname>/<reponame>.git

or

ssh://git@bitbucket.org /< accountname>/<reponame>.git

HTTPS URL format https://<accountname>@bitbucket.org/< accountname>/<reponame>.git

To make the change, go to a terminal on your local system and navigate to your bitbucketspacestation repo. Then, do the following:

  1. View your current repo configuration.
    You should see something similar to the following:

    $ cd ~/repos/bitbucketspacestation
    $ cat .git/config
    [core]
        repositoryformatversion = 0
        filemode = true
        bare = false
        logallrefupdates = true
        ignorecase = true
        precomposeunicode = true
    [remote "origin"]
        fetch = +refs/heads/*:refs/remotes/origin/*
        url = https://emmap1@bitbucket.org/emmap1/bitbucketspacestation.git
    [branch "master"]
        remote = origin
        merge = refs/heads/master

    As you can see, the url is using the HTTPS protocol. There are a number of ways to change this value, the easiest way is just to edit the repo's configuration file.

  2. Open the ~/repos/bitbucketspacestation/.git/config file with your favorite editor.
  3. Change the url value to use the SSH format for that repo.
    When you are done you should see something similar to the following:

    [remote "origin"]
        fetch = +refs/heads/*:refs/remotes/origin/*
        url = git@bitbucket.org:emmap1/bitbucketspacestation.git

Step 7. Make a change under the new protocol

  1. Edit the README file in your repository.
  2. Add a new line to the file, for example:

    Welcome to My First Repo
    -------------------------------
    This repo is a practice repo I am using to learn bitbucket.
    You can access this repo with SSH or with HTTPS.
  3. Save and close the file.
  4. Add and then commit your change to your local repo.

    $ git add README
    $ git commit -m "making a change under the SSH protocol"
  5. Push your changes.
    The system warns you that it is adding the Bitbucket host to the list of known hosts.

    $ git push
    Counting objects: 5, done.
    Delta compression using up to 2 threads.
    Compressing objects: 100% (2/2), done.
    Writing objects: 100% (3/3), 287 bytes, done.
    Total 3 (delta 1), reused 0 (delta 0)
    remote: bb/acl: newuserme is allowed. accepted payload.
    To git@bitbucket.org:newuserme/bb101repo.git
      056c29c..205e9a8 master -> master
  6. Open the repo Overview in Bitbucket to view your commit.
  Set up SSH for Mac OS/Linux

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.

Step 1. Ensure you have an SSH client installed

SSH is most likely included with your version of Mac OS or Linux. To make sure, do the following to verify your installation:

  1. From your terminal window, enter the following command, which identifies the version of SSH you have installed.
    If SSH is installed, you see something similar to the following:

    $ ssh -v
    OpenSSH_5.6p1, OpenSSL 0.9.8r 8 Feb 2011
    usage: ssh [-1246AaCfgKkMNnqsTtVvXxYy] [-b bind_address] [-c cipher_spec]
               [-D [bind_address:]port] [-e escape_char] [-F configfile]
               [-I pkcs11] [-i identity_file]
               [-L [bind_address:]port:host:hostport]
               [-l login_name] [-m mac_spec] [-O ctl_cmd] [-o option] [-p port]
    [-R [bind_address:]port:host:hostport] [-S ctl_path]
               [-W host:port] [-w local_tun[:remote_tun]]
               [user@]hostname [command]>

    If you have  ssh  installed, the terminal returns version information.
    If you don't have ssh installed, install it now.

  2. List the contents of your ~/.ssh directory.
    If you don't have an .ssh directory, don't worry, you'll create it the next section. If you have a .ssh directory or you may see something like this:

    $ ls -a ~/.ssh
    known_hosts

    If you have defined a default identity, you'll see the two id_* files:

    $ ls -a ~/.ssh
    .        ..        id_rsa        id_rsa.pub    known_hosts

    In this case, the default identity used RSA encryption (id_rsa.pub). If you want to use an existing default identity for your Bitbucket account, skip the next section and go to start the ssh-agent and load your keys.

Step 2. Set up your default identity

By default, the system adds keys for all identities to the /Users/<yourname>/.ssh directory on Mac OSX, or /home/<yourname>/.ssh on Linux. This procedure creates a default identity. If you have a default identity and you want to use it for Bitbucket, skip this step and go to start the ssh-agent and load your keys. If you have an existing default identity but you forgot the passphrase, you can also use this procedure to overwrite your default identity and create a fresh one.

Want to Use Multiple Identities?

You can create multiple SSH identities. Doing this is an advanced topic and beyond the scope of this tutorial. For information on how to create multiple identities, see Configure multiple SSH identities for GitBash, Mac OSX, & Linux.

Use the following procedure to create a new default identity.

  1. Open a terminal in your local system.
  2. Enter ssh-keygen at the command line.
    The command prompts you for a file where you want to save the key. If the .ssh directory doesn't exist, the system creates one for you.

    $ ssh-keygen
    Generating public/private rsa key pair.
    Enter file in which to save the key (/Users/emmap1/.ssh/id_rsa):
  3. Press the Enter or Return key to accept the default location.
  4. Enter and re-enter a passphrase when prompted.
    Unless you need a key for a process such as script, you should always provide a passphrase. The command creates your default identity with its public and private keys. The whole interaction will look similar to the following:

    $ ssh-keygen
    Generating public/private rsa key pair.
    Enter file in which to save the key (/Users/emmap1/.ssh/id_rsa):
    Created directory '/Users/emmap1/.ssh'.
    Enter passphrase (empty for no passphrase):
    Enter same passphrase again:
    Your identification has been saved in /Users/emmap1/.ssh/id_rsa.
    Your public key has been saved in /Users/emmap1/.ssh/id_rsa.pub.
    The key fingerprint is:
    4c:80:61:2c:00:3f:9d:dc:08:41:2e:c0:cf:b9:17:69 emmap1@myhost.local
    The key's randomart image is:
    +--[ RSA 2048]----+
    |*o+ooo.          |
    |.+.=o+ .         |
    |. *.* o .        |
    | . = E o         |
    |    o . S        |
    |   . .           |
    |     .           |
    |                 |
    |                 |
    +-----------------+
  5. List the contents of ~/.ssh to view the key files.

    $ ls -a ~/.ssh

Step 3. Start the ssh-agent and load your keys

If you are running OSX 10.6.8 or later you can skip this step.  The OSX 10.6.8 system asks for your connection parameters the first time you try to establish a SSH connection.  Then, it automatically starts the ssh-agent for you. If you don't have OSX 10.6.8 or are running another Linux operating system, do the following:

  1. Open a terminal window and enter the ps -e | grep [s]sh-agent command to see if the agent is running.

    $ ps -e | grep [s]sh-agent
     9060 ?? 0:00.28 /usr/bin/ssh-agent -l
  2. If the agent isn't running, start it manually with the following command:

    $ ssh-agent /bin/bash
  3. Load your new identity into the ssh-agent management program using the ssh-add command.

    $ ssh-add ~/.ssh/id_rsa
    Enter passphrase for /Users/emmap1/.ssh/id_rsa:
    Identity added: /Users/emmap1/.ssh/id_rsa (/Users/emmpa1/.ssh/id_rsa)
  4. Use the ssh-add command to list the keys that the agent is managing.

    $ ssh-add -l
    2048 7a:9c:b2:9c:8e:4e:f4:af:de:70:77:b9:52:fd:44:97 /Users/manthony/.ssh/id_rsa (RSA)

Step 4. Install the public key on your Bitbucket account

  1. From Bitbucket, choose avatar > Manage account from the application menu. 
    The system displays the Account settings page.
  2. Click SSH keys.
    The SSH Keys page displays. If you have any existing keys, those appear on this page.
  3. Back in your terminal window, copy the contents of your public key file.
    For example, in Linux you can cat the contents.

    $ cat ~/.ssh/id_rsa.pub

    In Mac OSX, the following command copies the output to the clipboard:

    $ pbcopy < ~/.ssh/id_rsa.pub
  4. Back in your browser, enter a Label for your new key, for example, Default public key.

  5. Paste the copied public key into the SSH Key field:
  6. Press Add key.
    The system adds the key to your account. Bitbucket sends you an email to confirm addition of the key. 

Step 5. Change an existing repo from HTTPS to the SSH protocol

The URL you use for a repo depends on which protocol you are using, HTTPS or SSH. The Clone button of the BitbucketSpaceStation repository has a quick way for you to see these URLS.

Experiment for a moment, clicking back and forth between the SSH and the HTTPS protocol links to see how the URLs differ. The table below shows the format based on protocol.

SSH URL format

git@bitbucket.org :< accountname>/<reponame>.git

or

ssh://git@bitbucket.org /< accountname>/<reponame>.git

HTTPS URL format https://<accountname>@bitbucket.org/< accountname>/<reponame>.git

To make the change, go to a terminal on your local system and navigate to your bitbucketspacestation repo. Then, do the following:

  1. View your current repo configuration.
    You should see something similar to the following:

    $ cd ~/repos/bitbucketspacestation
    $ cat .git/config
    [core]
        repositoryformatversion = 0
        filemode = true
        bare = false
        logallrefupdates = true
        ignorecase = true
        precomposeunicode = true
    [remote "origin"]
        fetch = +refs/heads/*:refs/remotes/origin/*
        url = https://emmap1@bitbucket.org/emmap1/bitbucketspacestation.git
    [branch "master"]
        remote = origin
        merge = refs/heads/master

    As you can see, the url is using the HTTPS protocol. There are a number of ways to change this value, the easiest way is just to edit the repo's configuration file.

  2. Open the ~/repos/bitbucketspacestation/.git/config file with your favorite editor.
  3. Change the url value to use the SSH format for that repo.
    When you are done you should see something similar to the following:

    [remote "origin"]
        fetch = +refs/heads/*:refs/remotes/origin/*
        url = git@bitbucket.org:emmap1/bitbucketspacestation.git

Step 6. Make a change under the new protocol

  1. From the local directory of your repository, create a new file called README.txt.
  2. Add the following text to the README.txt file:

    Welcome to My First Repo
    -------------------------------
    This repo is a practice repo I am using to learn bitbucket.
    You can access this repo with SSH or with HTTPS.
  3. Save and close the file.
  4. Add and then commit your change to your local repo.

    $ git add README.txt
    $ git commit -m "making a change under the SSH protocol"
  5. Push your changes.
    The system warns you that it is adding the Bitbucket host to the list of known hosts.

    $ git push
    Warning: Permanently added the RSA host key for IP address '207.223.240.182' to the list of known hosts.
    Counting objects: 5, done.
    Delta compression using up to 4 threads.
    Compressing objects: 100% (2/2), done.
    Writing objects: 100% (3/3), 314 bytes, done.
    Total 3 (delta 1), reused 0 (delta 0)
    remote: bb/acl: emmap1 is allowed. accepted payload.
    To git@bitbucket.org:emmap1/bitbucketspacestation.git
       d3bb337..f0b152f master -> master
  6. Open the repo Overview in Bitbucket to view your commit.

Was this helpful?

Thanks for your feedback!

1 Archived comment

  1. User avatar

    Daniel Reidler

    This tutorial was very helpful.

    10 Aug 2015
Powered by Confluence and Scroll Viewport