Up until this point, you have been using the secure hypertext transfer protocol (HTTPS) to communicate between your local system and Bitbucket. When you use HTTPS, you need to authenticate (supply a username and password) each time you take an action that communicates with the Bitbucket server. Who wants to do that? While you can specify the username in the DVCS configuration file, you don't want to store your password where anyone can see it. This page shows you how to use secure shell (SSH) to communicate with the Bitbucket server and avoid having to manually type a password.
Finally, 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.
Step 1. Read a quick overview of SSH concepts
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 2. Check if you have existing default Identity
The Git Bash shell comes with an SSH client. Do the following to verify your installation:
- Double-click the Git Bash icon to start a terminal session.
Enter the following command to verify the SSH client is available:
If you have
sshinstalled, go to the next step.
If you don't have
sshinstalled, install it now with your package manager.
List the contents of your
If you have not used SSH on Bash you might see something like this:
If you have a default identity already, you'll see two
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 create a config file.
Step 3. 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.
- Open a terminal in your local system.
ssh-keygenat the command line.
The command prompts you for a file to save the key in:
Press enter to accept the default key and path,
/c/Documents and Settings/manthony/.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:
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:
List the contents of
~/.sshto view the key files.
You should see something like the following:
The command created two files, one for the public key ( for example
id_rsa.pub) and one for the private key (for example,
Step 4. Create a SSH config file
Using your favorite text editor, create a new file (at
~/.ssh/config) or edit the file if it already exists.
Add an entry to the configuration file using the following format:
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
When you are done editing, your configuration looks similar to the following:
- Save and close the file.
- Restart the GitBash terminal.
Step 5. 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.
- Start GitBash.
Edit yourIf you don't have a
.bashrcfile 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 .
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.
- Save and close the file.
- Close GitBash, then reopen GitBash.
The system prompts you for your passphrase:
- Enter your passphrase.
After accepting your passphrase, the system displays the command shell prompt.
Verify that the script identity added your identity successfully by querying the SSH agent:
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 6. Install the public key on your Bitbucket account
- Open a browser and log into Bitbucket.
- Choose avatar > Manage Account from the menu bar.
The system displays the Account settings page.
- 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.
In your terminal window,
catthe contents of the public key file.
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).
Back in your browser, enter a Label for your new key, for example,
Default public key.
- Paste the copied public key into the SSH Key field.
- Click the Add key button:
The system adds the key to your account.
Return to the terminal window and verify your configuration by entering the following command.
The command message tells you which Bitbucket account can log in with that key.
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:
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.
Step 7. Configure your repository to use the SSH protocol
The URL you use for a repository depends on which protocol you are using, HTTPS and SSH. The Bitbucket repository Overview page has a quick way for you to see the one for your
bb101repo repo. On the repository's Overview page look for the Clone this repository line.
Experiment for a moment, click back and forth between the SSH and the HTTPS protocol links to see how the URLs differ. The table below shows the format for each DVCS based on protocol.
|SSH URL format||HTTPS URL format|
In the SSH format, the
accountname appears after
email@example.com. In HTTPS format, the
Go to terminal on your local system and navigate to your
bb101repo-practice repository. Then, do the following:
View your current repository configuration.
You should see something similar to the following:
As you can see, the
urlis using the HTTPS protocol. There are a number of ways to change this value, the easiest way is just to edit the repository's configuration file.
- Edit the
~/repos/bb101repo-practice/.git/configfile with your favorite editor.
urlvalue to use the SSH format for that repository.
When you are done the
originsection should contain something similar to the following:
Save your edits and close the file.
Step 8. Make a change under the new protocol
- Edit the
READMEfile in your
Add a new line to the file, for example:
- Save and close the file.
Add and then commit your change to your local repo.
Push your changes.
The system warns you that it is adding the Bitbucket host to the list of known hosts.
- Open the repo Overview in Bitbucket to view your commit.
Now, you should set up SSH for Mercurial through the TortoiseHg Workbench. If you are a Mac OSX or Linux user, you should have already worked through one page that covers SSH for both Git and Mercurial.